Study: Coding agents prefer AGENTS.md over API docs
rohanpaul_ai · x · 2026-08-30
Rohan Paul shares an empirical study on how coding agents discover, read, and write technical documentation. Tracking 3,033 documentation events across 557 real agent coding sessions and 33,097 agent-written pull requests, the authors found:
- Instruction files dominate: AGENTS.md and CLAUDE.md accounted for 35.4% of activity, while the agent's own plans and notes made up 25.1%.
- API docs ignored: API references were only 1.3%, and troubleshooting guides 0.4%.
- Non-linear workflow: The assumed "read-docs-then-write-code" loop barely appeared. Only 3 of 1,328 documentation reads led straight to a code edit, and no cases of agents checking work against docs were found.
The conclusion: Developers should prioritize writing AGENTS.md over API references, as that is what agents actually read.
More from coding & agent
- Simon Willison: code mode is the future of tool calling, if it can be sandboxed — springrod · 2026-10-16
- Agent named 'Ilya' reportedly scores 1.1pt higher on benchmarks — daniel_mac8 · 2026-10-16
- Gemini CLI fix: substring matching inlined unrequested binary files into model context — priyanshu1976 · 2026-10-16
- Building AI agents on real healthcare claims data: the domain work that makes them work — alex_verem · 2026-10-16
- OpenAI stealth-testing mysterious internal model 'Aeon' in Codex desktop app and Dots — cedric_chee · 2026-10-16
- Vibe-coded iPhone Duo sniping bot built with Codex in 17 minutes, 41 tests passing — xiaohu · 2026-10-16