A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all.
This article examines how AGENTS.md files impact AI coding agents, showing that well-structured agent docs can boost code quality by up to 15% while poorly designed ones can hurt performance. It outlines seven patterns that work—like progressive disclosure, step-by-step workflows, decision tables, real-code examples, and pairing “don’ts” with “dos”—and warns against overexploration from excessive context or warnings.
- AGENTS.md quality swings are huge: good ones boost output as much as upgrading from Haiku to Opus, bad ones perform worse than having no doc at all.
- Keep it short (100-150 lines) with details pushed to reference docs—bloated files cause "overexploration" where agents burn tens of thousands of tokens on irrelevant context and produce worse results (one case: completeness dropped 25% after the agent read 80K extraneous tokens for a two-line config change).
- Concrete structure wins: numbered step-by-step workflows cut missing files from 40% to 10% (+25% correctness), decision tables boosted best_practices by 25%, and real 3-10 line code snippets raised code_reuse by 20%.
- Always pair "don'ts" with concrete "dos," and scope docs to modular subsystems (~100 files) rather than writing sprawling repo-wide guides.
Teams tested dozens of AGENTS.md files across a big monorepo using AuggieBench, their internal eval suite. They took high-quality PRs, ran the same tasks with and without AGENTS.md, and scored outputs against golden PRs. The gap was huge: the best docs boosted quality as much as jumping from Haiku to Opus, while the worst hurt more than having no AGENTS.md at all. One file improved a routine bug fix by 25% but dropped completeness by 30% on a complex feature because the agent got lost in reference sections.
Seven patterns drove real gains. First, keep your main AGENTS.md to about 100–150 lines and push details into focused reference documents—this delivered 10–15% improvements in mid-size modules. Second, lay out numbered, step-by-step workflows; one six-step deployment guide cut missing wiring files from 40% to 10% and lifted correctness by 25%. Third, decision tables resolved common choices—React Query vs. Zustand tables alone upped best_practices by 25%. Fourth, include 3–10 line real-code snippets for core patterns; that nudged code_reuse up 20%. Fifth, enforce domain-specific rules sparingly—“Use Decimal for financials” caught precision bugs. Sixth, always pair “don’ts” with clear “dos.” And seventh, scope AGENTS.md to modular subsystems; 100-file modules outperformed sprawling repo-wide docs.
The biggest failure mode was overexploration. Files with long architecture overviews or long lists of warnings made agents load tens of thousands of tokens, roam through irrelevant docs, and produce incomplete fixes. In one case, a two-line config change task saw completeness fall by 25% after the agent swallowed 80K tokens of extraneous context. The fix: trim high-level architecture to boundaries, avoid vague “why” sections, and pair every prohibition with a concrete alternative.