I've had the same problems described here. I added an AGENTS.md to one of my projects and Claude Code started running way more tests than it needed to. I thought I was helping by being thorough with instructions, but the redundancy with my existing README was making it do extra work. The ablation experiment where they strip all docs and then the context file helps, that proves the added documentation is just a gap-filler, not a performance booster.
The bit about directory overviews not helping agents find files faster lines up with what I've seen. Agents are already decent at navigating codebases on their own; it's the unwritten team conventions they struggle with. My own AGENTS.md files have gotten shorter over time. Guardrails and conventions only, nothing else. Wrote up my approach to the cascading rules system here: https://reading.sh/the-definitive-guide-to-codex-cli-from-first-install-to-production-workflows-a9f1e7c887ab
I've had the same problems described here. I added an AGENTS.md to one of my projects and Claude Code started running way more tests than it needed to. I thought I was helping by being thorough with instructions, but the redundancy with my existing README was making it do extra work. The ablation experiment where they strip all docs and then the context file helps, that proves the added documentation is just a gap-filler, not a performance booster.
Thanks for sharing this insight!
The bit about directory overviews not helping agents find files faster lines up with what I've seen. Agents are already decent at navigating codebases on their own; it's the unwritten team conventions they struggle with. My own AGENTS.md files have gotten shorter over time. Guardrails and conventions only, nothing else. Wrote up my approach to the cascading rules system here: https://reading.sh/the-definitive-guide-to-codex-cli-from-first-install-to-production-workflows-a9f1e7c887ab