Augment Code ran a systematic study on AGENTS.md files and the results are stark. Good documentation can boost AI coding agent performance by up to 25%, roughly equivalent to jumping from Claude Haiku to Claude Opus. Bad documentation makes things 30% worse than having no docs at all.
Using their internal eval suite AuggieBench, the team compared agent outputs against golden PRs from real development work. The patterns that work are specific and measurable. Keep files to 100-150 lines with progressive disclosure into reference docs. Write procedural workflows: one six-step deployment workflow increased correctness 25% and completeness 20%. Build decision tables that resolve ambiguity before code gets written. Pair every "don't" with a concrete "do." Include short codebase examples of 3-10 lines. Slava Zhenylenko and the Augment Code team measured all of this directly.
The killer failure mode is over-editing, basically context rot. Stuff too much architecture overview into your docs and the agent goes wandering. One AGENTS.md file boosted best practices 25% on a routine bug fix but tanked completeness 30% on a feature task in the same module. The agent read the reference section, opened dozens of markdown files trying to verify its approach, created unnecessary abstractions, and shipped something incomplete. Files with 15+ sequential warnings and no actionable alternatives made agents cautious and less productive.
If you're writing AGENTS.md files, treat them like onboarding a junior dev who reads literally everything. Cut the sprawl, be procedural, show what right looks like. And if your module has 500K of surrounding specs, fix that environment first. The best AGENTS.md in the world can't save you from documentation chaos.