AGENTS.md and agent notes are 60.5% of what coding agents read, API docs 1.3%

Two Peking University researchers, Zhijun Gao and Jing Chen, went looking for what coding agents actually read, and found that the documentation industry has been optimising the wrong artefacts. Across 557 real agentic coding sessions from the SWE-chat corpus — 94,813 development events containing 3,033 documentation interactions — 60.5% of documentation activity targeted files that exist only because agents exist: instruction files such as AGENTS.md and CLAUDE.md (35.4%) and agent working notes, meaning plans, thoughts/ directories, brainstorms and verification logs (25.1%). API references, the focus of most documentation tooling, accounted for 1.3%. Troubleshooting docs accounted for 0.4%.

Figure 1 from the paper: document types, what follows consultation, what triggers it, which interaction stages are attested, and which artefact a pull request touches first. Credit: Gao and Chen, arXiv:2608.20195.

#What agents open

Instruction files receive roughly 27× as many interactions as API references. The nine genres at the traditional core of documentation research together make up 10.6% — a boundary the authors admit is contestable, since folding in README, configuration and requirements docs raises the classical share to 33.8%.

#Reading the docs does not lead to writing the code

The pattern everyone assumes — read the documentation, then write the code — barely appears in the traces. The adjacent transition probability is 0.002: three occurrences among 1,328 documentation reads. A read is far more likely to be followed by another read (0.270) or by reasoning (0.245). Widening to a three-event horizon, the unadjusted lift for code editing is 1.05, and a stage-adjusted model puts it above unity (OR 1.33 [1.09, 1.62]) — the authors call the coupling unresolved rather than confirmed.

What is robust runs opposite to what "agent-friendly documentation" advice predicts. Testing and building are less frequent in the three events after a consultation: running a test at lift 0.23 (adjusted OR 0.39 [0.25, 0.60]), building at lift 0.15 (OR 0.25 [0.14, 0.44]). No documentation-based validation sequence was observed at all — zero events in which prose served as an oracle to check code. Gao and Chen conclude that two properties routinely asserted of agent-friendly docs, actionability and verifiability, "lack consistent behavioural support in this corpus."

Consultation is also not a distress signal. It is self-initiated 70.2% of the time — agent initiative or an implementation need — against 7.5% driven by a failure, a 9.3× ratio. Reading documentation was the first recovery move in just 109 of 2,034 failure episodes (5.4%).

#Docs follow code, and agents edit their own instructions

The second dataset, 33,097 agentic pull requests from AIDev with 690,260 classified file-level changes, covers direction. 41.5% of agentic PRs change documentation, and 32.0% change code and docs together. Where ordering is observable across commits, code comes first in 82.5% of cases. Among the most-changed individual doc files: AGENTS.md (692 PRs), CLAUDE.md (362), copilot-instructions.md (287). Agents are rewriting the files that configure agents.

Production of documentation runs at 0.87× the rate of consumption (1,401 events versus 1,615). The authors therefore replace the assumed linear journey — discover, retrieve, interpret, apply, validate, update — with a two-lobed cycle: a recurrent consultation loop that mostly feeds reasoning and more documentation, only loosely coupled to a largely independent code-modification loop.

#Why it matters

If you maintain a repository that agents contribute to, this is the first behavioural denominator for advice that has so far been traded on intuition. It argues for spending finite documentation effort on the correctness of instruction files rather than on polishing API reference prose, for self-contained documents over richly cross-linked ones ("follow-reference" behaviour is entirely unattested), and for treating agent-authored plans and thoughts/ directories as a maintenance surface that no review checklist or staleness metric currently has a category for. For verification the authors suggest executable artefacts — runnable examples, doctests, schema contracts — rather than prose an agent is trusted to honour, flagged as a hypothesis for intervention studies, not a finding.

The caveats are the authors' own and they are substantial. This is an observational preprint, not a controlled experiment: it measures what agents did, not what helps them. Documentation is identified by file path, so docstrings and in-source comments are invisible and every absolute rate is a lower bound. The agent_working_note category — a quarter of all events, and one of the headline numbers — rests on language-model classification of 500 ambiguous paths with no human validation, and the paper calls its precise share provisional. SWE-chat is opt-in telemetry, 87% of it from a single agent family. Whether these files help at all remains contested: Lulla et al. tie the presence of an AGENTS.md to 28.64% lower median runtime and 16.58% fewer output tokens, while other work Gao and Chen cite finds mixed task-level results. The pipeline, coding scheme and event-level data are released.