A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all
21 hours ago
- #Documentation-Best-Practices
- #AGENTS-MD-Study
- #AI-Coding-Agents
- Effective AGENTS.md files can significantly improve AI coding agent performance equivalent to upgrading model quality, while poor ones degrade results.
- Optimal AGENTS.md length is 100–150 lines with progressive disclosure; longer files tend to reverse gains, especially in modules around 100 core files.
- Procedural workflows boost correctness and completeness, with one example reducing missing files from 40% to 10% and improving task completion.
- Decision tables resolve codebase ambiguities upfront, enhancing best_practices by 25% in cases like choosing React Query vs Zustand.
- Including real code snippets (3–10 lines) improves code_reuse by 20%, while domain-specific rules help when specific and enforceable.
- Pairing 'don't' statements with actionable 'do' alternatives prevents overexploration; excessive warnings can reduce completeness by 20%.
- AGENTS.md files in isolated submodules perform best; cross-cutting or overly documented environments (e.g., 500K+ characters) hinder effectiveness.
- Common pitfalls include overexploration from too much architecture detail and warnings, leading to context rot and incomplete solutions.
- Discovery rates show AGENTS.md is auto-loaded 100%, referenced docs are read 90%+, while orphaned docs are rarely accessed (<10%).
- Migrating existing docs involves trimming READMEs for agents, referencing high-quality content, and controlling surrounding documentation sprawl.