{
  "@context": "https://schema.org",
  "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-02-24-writing-a-good-agents-md/#webpage",
  "@type": [
    "WebPage",
    "ArchiveComponent"
  ],
  "articleBody": "An `AGENTS.md` (or `GEMINI.md`) file is the single highest-leverage configuration point for coding agents. It's injected into **every** conversation, acting as the agent's onboarding document to your codebase. But research shows that doing it wrong actively hurts performance. Here's how to do it right, backed by data from [\"Evaluating AGENTS.md\" (ETH Zurich, 2025)](https://arxiv.org/abs/2602.11988) and [practical experience from HumanLayer](https://www.humanlayer.dev/blog/writing-a-good-claude-md).\n\n## The Data Says: Less Is More\n\n- **Auto-generated AGENTS.md files reduce task success rates by ~3%** on average across multiple agents and models, while increasing inference cost by over 20% ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **Human-written AGENTS.md files only marginally improve performance (~4%)**, and still increase cost by up to 19% due to extra steps the agent takes.\n- **Stronger models don't generate better context files.** GPT-5.2-generated files improved performance on one benchmark by 2% but degraded it on another by 3% ([§4.4](https://arxiv.org/html/2602.11988v1#S4)).\n- **Codebase overviews in AGENTS.md don't help agents navigate faster.** Agents found relevant files in roughly the same number of steps with or without an overview section ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **LLM-generated files are redundant with existing docs.** When all other documentation was removed, LLM-generated files actually improved performance by 2.7%—they only hurt when they duplicate what's already discoverable ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **Instructions ARE followed—that's the problem.** Agents respect AGENTS.md instructions, but unnecessary requirements make tasks harder, increasing reasoning tokens by 14–22% ([§4.3](https://arxiv.org/html/2602.11988v1#S4)).\n\n## What to Include\n\n- **The WHAT:** Your tech stack, project structure, and what each part does. Critical for monorepos—tell the agent what the apps, shared packages, and services are.\n- **The WHY:** The purpose of the project and its key components. Help the agent understand intent, not just structure.\n- **The HOW:** How to build, test, and verify changes. Include non-obvious tooling (e.g., `uv` instead of `pip`, `bun` instead of `npm`). Tools mentioned in AGENTS.md get used 160x more often than unmentioned ones ([§4.3](https://arxiv.org/html/2602.11988v1#S4)).\n\n## What NOT to Include\n\n- **Detailed codebase overviews or directory listings.** The paper found these don't help agents navigate faster, and agents can discover structure themselves.\n- **Code style guidelines.** Use linters and formatters instead—they're faster, cheaper, and deterministic. LLMs are in-context learners and will follow existing patterns in your code.\n- **Task-specific instructions** that only apply sometimes. Since AGENTS.md goes into every session, non-universal instructions dilute focus. Frontier models can reliably follow ~150–200 instructions; the agent harness already uses ~50 of those.\n- **Auto-generated content.** Don't use `/init` or let the agent write its own AGENTS.md. The data shows this hurts more than it helps.\n\n## How to Structure It\n\n- **Keep it short.** General consensus is <300 lines; HumanLayer keeps theirs under 60 lines. Every line goes into every session—make each one count.\n- **Use progressive disclosure.** Don't put everything in AGENTS.md. Instead, keep task-specific docs in separate files (e.g., `agent_docs/running_tests.md`, `agent_docs/database_schema.md`) and list them in AGENTS.md with brief descriptions so the agent reads them only when relevant.\n- **Prefer pointers over copies.** Reference `file:line` locations rather than embedding code snippets that will go stale.\n- **Write it yourself, deliberately.** A bad line in AGENTS.md cascades into bad plans, bad code, and bad results across every session. Treat it like infrastructure, not a scratchpad.\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n",
  "authors": [],
  "captured_at": "2026-09-27T19:29:15.293681927+00:00",
  "category": "programming",
  "content_html": "<p>An <code>AGENTS.md</code> (or <code>GEMINI.md</code>) file is the single highest-leverage configuration point for coding agents. It's injected into <strong>every</strong> conversation, acting as the agent's onboarding document to your codebase. But research shows that doing it wrong actively hurts performance. Here's how to do it right, backed by data from <a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/abs/2602.11988\">&quot;Evaluating AGENTS.md&quot; (ETH Zurich, 2025)</a> and <a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://www.humanlayer.dev/blog/writing-a-good-claude-md\">practical experience from HumanLayer</a>.</p>\n<h2>The Data Says: Less Is More</h2>\n<ul>\n<li><strong>Auto-generated AGENTS.md files reduce task success rates by ~3%</strong> on average across multiple agents and models, while increasing inference cost by over 20% (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.2</a>).</li>\n<li><strong>Human-written AGENTS.md files only marginally improve performance (~4%)</strong>, and still increase cost by up to 19% due to extra steps the agent takes.</li>\n<li><strong>Stronger models don't generate better context files.</strong> GPT-5.2-generated files improved performance on one benchmark by 2% but degraded it on another by 3% (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.4</a>).</li>\n<li><strong>Codebase overviews in AGENTS.md don't help agents navigate faster.</strong> Agents found relevant files in roughly the same number of steps with or without an overview section (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.2</a>).</li>\n<li><strong>LLM-generated files are redundant with existing docs.</strong> When all other documentation was removed, LLM-generated files actually improved performance by 2.7%—they only hurt when they duplicate what's already discoverable (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.2</a>).</li>\n<li><strong>Instructions ARE followed—that's the problem.</strong> Agents respect AGENTS.md instructions, but unnecessary requirements make tasks harder, increasing reasoning tokens by 14–22% (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.3</a>).</li>\n</ul>\n<h2>What to Include</h2>\n<ul>\n<li><strong>The WHAT:</strong> Your tech stack, project structure, and what each part does. Critical for monorepos—tell the agent what the apps, shared packages, and services are.</li>\n<li><strong>The WHY:</strong> The purpose of the project and its key components. Help the agent understand intent, not just structure.</li>\n<li><strong>The HOW:</strong> How to build, test, and verify changes. Include non-obvious tooling (e.g., <code>uv</code> instead of <code>pip</code>, <code>bun</code> instead of <code>npm</code>). Tools mentioned in AGENTS.md get used 160x more often than unmentioned ones (<a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://arxiv.org/html/2602.11988v1#S4\">§4.3</a>).</li>\n</ul>\n<h2>What NOT to Include</h2>\n<ul>\n<li><strong>Detailed codebase overviews or directory listings.</strong> The paper found these don't help agents navigate faster, and agents can discover structure themselves.</li>\n<li><strong>Code style guidelines.</strong> Use linters and formatters instead—they're faster, cheaper, and deterministic. LLMs are in-context learners and will follow existing patterns in your code.</li>\n<li><strong>Task-specific instructions</strong> that only apply sometimes. Since AGENTS.md goes into every session, non-universal instructions dilute focus. Frontier models can reliably follow ~150–200 instructions; the agent harness already uses ~50 of those.</li>\n<li><strong>Auto-generated content.</strong> Don't use <code>/init</code> or let the agent write its own AGENTS.md. The data shows this hurts more than it helps.</li>\n</ul>\n<h2>How to Structure It</h2>\n<ul>\n<li><strong>Keep it short.</strong> General consensus is &lt;300 lines; HumanLayer keeps theirs under 60 lines. Every line goes into every session—make each one count.</li>\n<li><strong>Use progressive disclosure.</strong> Don't put everything in AGENTS.md. Instead, keep task-specific docs in separate files (e.g., <code>agent_docs/running_tests.md</code>, <code>agent_docs/database_schema.md</code>) and list them in AGENTS.md with brief descriptions so the agent reads them only when relevant.</li>\n<li><strong>Prefer pointers over copies.</strong> Reference <code>file:line</code> locations rather than embedding code snippets that will go stale.</li>\n<li><strong>Write it yourself, deliberately.</strong> A bad line in AGENTS.md cascades into bad plans, bad code, and bad results across every session. Treat it like infrastructure, not a scratchpad.</li>\n</ul>\n<hr />\n<p>Thanks for reading! If you have any questions or feedback, please let me know on <a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://twitter.com/_philschmid\">Twitter</a> or <a target=\"_blank\" rel=\"noopener noreferrer\" href=\"https://www.linkedin.com/in/philipp-schmid-a6a2bb196/\">LinkedIn</a>.</p>\n",
  "content_markdown": "An `AGENTS.md` (or `GEMINI.md`) file is the single highest-leverage configuration point for coding agents. It's injected into **every** conversation, acting as the agent's onboarding document to your codebase. But research shows that doing it wrong actively hurts performance. Here's how to do it right, backed by data from [\"Evaluating AGENTS.md\" (ETH Zurich, 2025)](https://arxiv.org/abs/2602.11988) and [practical experience from HumanLayer](https://www.humanlayer.dev/blog/writing-a-good-claude-md).\n\n## The Data Says: Less Is More\n\n- **Auto-generated AGENTS.md files reduce task success rates by ~3%** on average across multiple agents and models, while increasing inference cost by over 20% ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **Human-written AGENTS.md files only marginally improve performance (~4%)**, and still increase cost by up to 19% due to extra steps the agent takes.\n- **Stronger models don't generate better context files.** GPT-5.2-generated files improved performance on one benchmark by 2% but degraded it on another by 3% ([§4.4](https://arxiv.org/html/2602.11988v1#S4)).\n- **Codebase overviews in AGENTS.md don't help agents navigate faster.** Agents found relevant files in roughly the same number of steps with or without an overview section ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **LLM-generated files are redundant with existing docs.** When all other documentation was removed, LLM-generated files actually improved performance by 2.7%—they only hurt when they duplicate what's already discoverable ([§4.2](https://arxiv.org/html/2602.11988v1#S4)).\n- **Instructions ARE followed—that's the problem.** Agents respect AGENTS.md instructions, but unnecessary requirements make tasks harder, increasing reasoning tokens by 14–22% ([§4.3](https://arxiv.org/html/2602.11988v1#S4)).\n\n## What to Include\n\n- **The WHAT:** Your tech stack, project structure, and what each part does. Critical for monorepos—tell the agent what the apps, shared packages, and services are.\n- **The WHY:** The purpose of the project and its key components. Help the agent understand intent, not just structure.\n- **The HOW:** How to build, test, and verify changes. Include non-obvious tooling (e.g., `uv` instead of `pip`, `bun` instead of `npm`). Tools mentioned in AGENTS.md get used 160x more often than unmentioned ones ([§4.3](https://arxiv.org/html/2602.11988v1#S4)).\n\n## What NOT to Include\n\n- **Detailed codebase overviews or directory listings.** The paper found these don't help agents navigate faster, and agents can discover structure themselves.\n- **Code style guidelines.** Use linters and formatters instead—they're faster, cheaper, and deterministic. LLMs are in-context learners and will follow existing patterns in your code.\n- **Task-specific instructions** that only apply sometimes. Since AGENTS.md goes into every session, non-universal instructions dilute focus. Frontier models can reliably follow ~150–200 instructions; the agent harness already uses ~50 of those.\n- **Auto-generated content.** Don't use `/init` or let the agent write its own AGENTS.md. The data shows this hurts more than it helps.\n\n## How to Structure It\n\n- **Keep it short.** General consensus is <300 lines; HumanLayer keeps theirs under 60 lines. Every line goes into every session—make each one count.\n- **Use progressive disclosure.** Don't put everything in AGENTS.md. Instead, keep task-specific docs in separate files (e.g., `agent_docs/running_tests.md`, `agent_docs/database_schema.md`) and list them in AGENTS.md with brief descriptions so the agent reads them only when relevant.\n- **Prefer pointers over copies.** Reference `file:line` locations rather than embedding code snippets that will go stale.\n- **Write it yourself, deliberately.** A bad line in AGENTS.md cascades into bad plans, bad code, and bad results across every session. Treat it like infrastructure, not a scratchpad.\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n",
  "dateCreated": "2026-09-27T19:29:15.293681927+00:00",
  "date_created": "2026-02-24T00:00:00+00:00",
  "date_modified": "2026-02-24T00:00:00+00:00",
  "date_published": "2026-02-24T00:00:00+00:00",
  "description": "Learn what to include, what to skip, and how to structure your AGENTS.md for best results.",
  "external_url": "https://www.philschmid.de/writing-good-agents",
  "git": {
    "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e",
    "path": "items/philschmid-de/2026/02/2026-02-24-writing-a-good-agents-md.md",
    "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2026/02/2026-02-24-writing-a-good-agents-md.md"
  },
  "id": "urn:aggr:item:9dc59ed6b47deca4cb11de9f119027a70175d11b",
  "isBasedOn": {
    "@id": "https://www.philschmid.de/writing-good-agents"
  },
  "mainEntity": {
    "@id": "https://www.philschmid.de/writing-good-agents",
    "@type": "CreativeWork",
    "archivedAt": {
      "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-02-24-writing-a-good-agents-md/#webpage"
    },
    "dateModified": "2026-02-24T00:00:00+00:00",
    "datePublished": "2026-02-24T00:00:00+00:00",
    "headline": "Writing a Good AGENTS.md",
    "timeRequired": "PT3M",
    "url": "https://www.philschmid.de/writing-good-agents",
    "wordCount": 540
  },
  "name": "Archived snapshot: Writing a Good AGENTS.md",
  "preview": null,
  "reading_minutes": 3,
  "replicated_at": null,
  "source": "philschmid-de",
  "source_name": "philschmid.de - RSS feed",
  "summary": "Learn what to include, what to skip, and how to structure your AGENTS.md for best results.",
  "tags": [],
  "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00",
  "title": "Writing a Good AGENTS.md",
  "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2026-02-24-writing-a-good-agents-md/",
  "word_count": 540
}