Skimming this morning's cs.SE listing I braced for another SWE-bench variant and instead hit a paper that went and measured something nobody had bothered to: which documentation coding agents actually open, where in a task they open it, and what they do immediately afterwards. No new benchmark, no new scaffold — just 94,813 development events pulled out of real agent transcripts. It reordered my mental model of what "docs for agents" even means. The thesis: the documentation your agent reads is mostly documentation your agent wrote.
What it does#
From Agent Behaviour to Agent-Friendly Documentation by Zhijun Gao and Jing Chen is a behaviour-grounded observational study, not a system paper. They combine two public corpora with complementary blind spots. SWE-chat gives them real command-line agent sessions with full transcripts — user messages, agent messages, tool calls, tool results, code changes — from which they sample 557 parseable sessions stratified by agent and session length, yielding 94,813 development events of which 3,033 touch documentation. AIDev gives them 33,097 agent-authored pull requests on public GitHub repos and 690,260 file-level change records. SWE-chat has process but no merge outcomes; AIDev has artefacts but no trajectories. They use them as complementary sources and never pool the units of analysis.
The move that makes the paper work is the taxonomy. Their initial coding scheme was inherited from pre-LLM documentation research — API reference, architecture, schema, installation, examples, testing, contributing, changelog, troubleshooting — and it dumped the majority of agent documentation events into a residual bucket. They had to invent two categories that did not exist before 2024: agent_instruction (AGENTS.md, CLAUDE.md, SKILL.md, Cursor and Copilot rule files) and agent_working_note (plans, thoughts/ directories, brainstorms, review logs the agent writes for its own use). Everything downstream falls out of that split, which is itself the finding: the file-type taxonomies we inherited are blind to most of what agents actually do with prose.
The key result#
Agent instruction files account for 1,074 documentation events, 35.4% of the corpus. Agent working notes account for 760, 25.1%. Together, agent-facing artefacts are 60.5% of every documentation interaction observed (session-cluster 95% CI 53.9–66.5%). The nine genres at the traditional core of documentation research total 323 events — 10.6%. API references alone: 40 events, 1.3%. Troubleshooting documents, the genre written specifically for when things break, account for 11 events across the entire corpus — 0.4%. Instruction files receive roughly 27x the interactions of API references. And the asymmetry is not a writing artefact: agent-facing files are 57.4% of consultation events and 63.7% of production events, so agents both read and write them more than anything else in the repo.
Why it matters#
If you maintain a repository that agents contribute to, this is a budget-allocation result. The marginal hour you spend polishing an API reference is going into a surface that gets touched 1.3% of the time, while CLAUDE.md — the highest-traffic document in the repo by a wide margin — is the one most teams treat as a scratch file nobody reviews. Two structural findings sharpen that. First, documentation reads are followed by further documentation reads at a transition probability of 0.270, while Follow-reference — an agent traversing a link into another document — is entirely unattested in the corpus. Zero events. The beautifully cross-linked docs site is not being navigated; self-contained documents with locally retrievable structure are what the behaviour supports. Second, documentation interaction is not an orientation-phase activity: 54.4% of events land during debugging and 27.2% during implementation, against 15.2% during orientation. A mental model where the agent reads the docs at the top of the task and then goes off and codes is not what the traces show.
The harder finding is what it does to two pieces of received wisdom. Everybody says agent-friendly docs should be actionable and verifiable. Both got measured and neither survives cleanly. The adjacent transition probability from a documentation read to a code edit is 0.002, the unadjusted three-event lift is 1.05, and the coupling only clears unity under a stage-adjusted model (OR 1.33 [1.09, 1.62]). Verifiability describes no observed behaviour at all — zero documentation-based validation sequences, with consultation actually associated with less immediate testing (adjusted OR 0.39 [0.25, 0.60]). Consultation is self-initiated 70.2% of the time and failure-driven only 7.5%; docs were the first recovery action in 109 of 2,034 failure episodes, 5.4%. The authors' descriptive model is a two-lobed cycle: a recurrent consultation lobe whose strongest outgoing edge runs into reasoning (0.245) rather than action, loosely coupled to a largely independent code-modification loop. The practical read is blunt — prose is not a specification your agent will check itself against. If you want a verification step to exist, it has to be something the agent can execute: doctests, runnable examples, schema contracts, a test command. Prose it must be trusted to honour is prose it demonstrably does not honour.
There is a second-order implication worth sitting with. Agent working notes are now a quarter of all documentation traffic and they land in repositories as committed, durable artefacts — plans, thoughts/ directories, verification logs. No repository hygiene tool, review checklist, or documentation-quality metric currently has a category for them. That is a maintenance surface accumulating faster than anyone is measuring it, and the paper is explicit that it measured volume, not staleness or cost.
The caveats#
Observational, not interventional. Every result is an association in traces. To the authors' credit they say so repeatedly and decline to over-claim — they explicitly refuse to rank recovery strategies because only 11 episodes had observable outcomes, giving an interval of 35.4–84.8% that overlaps every alternative.
The 10.6% figure rests on a contestable boundary. Add README, configuration, and requirements documentation and "classical" documentation rises to 33.8%. The robust claims are only at the extremes: 1.3% API reference, 0.4% troubleshooting.
Whether working notes are "documentation" is a definitional choice. Exclude them entirely and instruction files are still 47.2% of what remains, so the direction survives either way — but the headline 60.5% depends on counting them.
Sampling is non-proportional. SWE-chat is developer-contributed CLI sessions, oversampled for minority agent tools, which is why agent-level statistics are reported separately rather than pooled. This is not a random sample of all agentic work.
Extraction undercounts by construction. Agents that route file operations through shell commands hide file access inside command strings; any trace analysis keyed on tool names systematically misses those. The authors flag this as a warning for anyone else building on these corpora.
The takeaway#
Three things I am filing away. The instruction file is the highest-traffic documentation surface in my repos and deserves the review discipline I currently reserve for code. Linked documentation is not traversed, so self-contained beats well-cross-referenced. And prose is not a spec — across 3,033 documentation events, not one instance of an agent validating its work against written documentation was observed. What I am changing today: pulling the invariants out of my CLAUDE.md prose and into something runnable that an agent will actually invoke, and adding plan files and thoughts/ to the set of things I review before merge instead of letting them silt up in the repository.
Paper: From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation — Zhijun Gao, Jing Chen (arXiv:2608.20195, 20 August 2026).