How AGENTS.md Quality Shapes Coding Agent Output

Augment Code ran structured benchmarks on their internal codebase and found that a well-written AGENTS.md file improves agent output by 10-15% - roughly the gap between Claude Haiku and Opus. A bad one actually performs worse than having none at all. The practical findings are specific: keep files under 150 lines, use numbered workflows instead of prose, pair every prohibition with a concrete alternative, and favor decision tables when multiple valid approaches exist. One standout data point - agents that hit verbose architecture docs loaded 80K irrelevant tokens and lost 25% on completeness. Discovery rates matter too: AGENTS.md hits 100%, nested READMEs drop to 40%, and orphan docs in side folders barely register. As Claude Code, Copilot, and Cursor all lean harder on repo-level instructions, writing good agent documentation is becoming a genuine engineering skill.