Augment Code just published research that should make every team using coding agents rethink their docs. Slava Zhenylenko and the team ran a systematic study using their internal AuggieBench eval suite, measuring how AGENTS.md files affect agent behavior on real tasks pulled from high-quality PRs in a large monorepo. The headline finding: a well-structured AGENTS.md file gave performance gains equivalent to upgrading from Claude Haiku to Claude Opus. A bad one made things worse than having no documentation at all.

The specifics matter. Files between 100 and 150 lines with focused reference documents delivered 10-15% improvements across all metrics in mid-size modules. Procedural workflows with numbered steps cut missing wiring files from 40% to 10% in one deployment scenario and improved correctness by 25%. Decision tables that resolved ambiguities upfront boosted best practices scores by 25%. Short code snippets from actual production code (think 3-10 lines) improved code reuse by 20%

Same file, different results. In testing, one AGENTS.md boosted best practices by 25% on a routine bug fix while dropping completeness by 30% on a complex feature task in the same module. The agent got distracted by reference sections, opened dozens of markdown files, created unnecessary abstractions, and shipped something incomplete. Files longer than 150 lines started reversing gains. Stacking 15+ prohibitions without concrete alternatives made agents cautious and less productive. The worst-performing docs sat on top of massive documentation sprawl, sometimes 500K characters or more of surrounding specs that agents would read instead of actual guidance. A recent Agent Reading Test revealed that agents often struggle to prioritize core instructions over dense supplementary material.

The ecosystem fragmentation doesn't help. Cursor pushes AGENTS.md as their preferred format. Replit uses .ai/config files instead. GitHub Copilot lacks explicit support, and Hacker News commenters report that VS Code Copilot sometimes misses nested AGENTS.md files entirely. Augment's recommendation to spread focused AGENTS.md files throughout subdirectories rather than relying on a single root file matches how agents actually discover and consume context. It's practical advice. But until tool makers agree on a standard, teams are optimizing for a moving target.