Almost everything written about documenting software for AI agents is advice. Zhijun Gao and Jing Chen went and measured it instead. Their August 2026 paper (arXiv 2608.20195) instruments 557 agentic coding sessions, 94,813 events, 3,033 documentation interactions, and a separate corpus of 33,097 agentic pull requests, then asks a plain question: which documents does a coding agent open, when, and what happens next. The answer reorders the work. The documents agents read most are the ones written for agents, and the reference material teams spend the most effort on is nearly untouched.
What agents actually open.
The headline number is a hierarchy, not a total. Agent-facing artifacts, meaning instruction files and the notes agents write for themselves, are 60.5% of all documentation interactions. Split that: instruction files (AGENTS.md, CLAUDE.md, SKILL.md, editor rule files) are 35.4%, and agent working notes (plans, thought logs, review scratchpads the agent authored in an earlier turn) are 25.1%. The nine classical documentation genres together come to 10.6%. Inside that, API references get 1.3% and troubleshooting docs get 0.4%.
If your documentation budget is finite, and it is, that ratio is a reallocation instruction. Most teams treat the instruction file as a preamble to the real documentation and spend accordingly. The measurements say the spending is backwards: the agent-facing half of a docs budget lives in one file, and it deserves the care you were going to put into navigation.
If a vendor has quoted you a documentation portal as part of an AI rollout, this is the number to ask them about. What share of that spend is aimed at something your agent opens 1.3% of the time, and what does the agent-facing half of the work actually consist of? A good answer names the instruction file. A bad one talks about information architecture.
Reading and working are two separate loops.
The finding underneath the hierarchy is stranger and more useful. Reading a document almost never leads directly to changing code. The probability of a code edit immediately following a documentation read is 0.002, three events across 1,328 reads. What reads lead to is more reads (0.270) and reasoning (0.245). The authors describe the behaviour as two loosely coupled lobes: a consultation loop that spins on itself, and a code-modification loop that runs largely independently of it.
- 0.270 read leads to another read
- 0.245 read leads to reasoning
- 7.5% of doc interactions are failure-driven
- 5.4% of failure episodes opened a doc first
Two things follow. One is a correction to a common assumption: writing better troubleshooting documentation will probably not make your agent recover better, because the agent mostly does not go looking. The other is about shape. Agents read in runs and, in this data, never followed a cross-reference. Zero attested events. A document that says "see the authentication guide for details" is a document that ends there. Whatever is load-bearing has to be in the page the agent lands on.
We reached the same conclusion from the retrieval side in the note on agent memory: self-contained, deterministically retrievable surfaces beat anything that assumes navigation. Link graphs still earn their keep for the humans, for dedup, and for marking what has not been written yet. They just are not a delivery mechanism.
Prose is not a spec.
The most uncomfortable number in the paper is a zero. Across every session they instrumented, there were no observed events of an agent checking code against documentation. Consultation was also associated with less immediate testing, not more: a lift of 0.23, meaning the pairing showed up at about a quarter of the rate chance would predict. An instruction file is honoured at generation time, in the moment, or it is not honoured at all. Nothing goes back and audits the result against the sentence.
The authors offer a hypothesis rather than a result here, and it deserves the distinction: if you want a rule validated, make the artifact executable, meaning a doctest, a runnable example, a schema contract. Something with a pass or fail. They are careful about this, and section 6.2 of the paper is an honesty list of advice their data does not support, including exactly the claims that documentation should be actionable or verifiable. Their zero-validation observation is what it is: a measured absence, not a proof that executable docs work better. Nobody has measured that yet.
We operate on the same instinct for a reason that predates the paper. The rule that no writing from our parent group contains an em dash is not a line in a style guide. It is a hook that blocks the write. The rule that a database migration gets applied by a human before merge is not a paragraph, it is a gate on the pipeline. Every rule we wrote as a sentence and expected to hold got broken eventually, quietly, by a well-meaning agent doing its best.
# as a sentence, in CLAUDE.md: honoured at generation time, or not at all
No em dashes. Use a colon, a comma, parentheses, or two sentences.
# as a check, in .git/hooks/pre-commit: it fails the write
grep -nP '\x{2014}' "$FILE" && exit 1Writing the rule down is how you communicate it. Wiring it into a check is how you enforce it. This study did not teach us that, but it is the first thing we have seen that explains the mechanism: there is no audit step in the loop for prose to be audited by.
The notes your agent leaves behind.
The quarter of all documentation traffic that goes to agent working notes is the finding nobody has a process for. Agents write plans, logs, and review notes to themselves, and those files stay. The paper's reading of why is convincing: a bounded context window makes documentation a form of working memory rather than reference. The agent writes things down because it will forget them, exactly like a person with a notebook and a long meeting.
The consequence is a maintenance surface that arrived without a category. Repo hygiene tooling does not know what a stale agent plan is. Code review checklists have no line for it. It is not source, not documentation, not config, and it accumulates. Every fleet running agents at any scale has this, including ours: phase ledgers, session notes, plans committed alongside the work they described. Nobody has been auditing them.
None of the responses here are expensive. They are mostly a reallocation of effort you are already spending:
- Spend the documentation budget on the instruction file.
It carries 35.4% of the traffic on its own. Correctness, precision, and currency in that one file beat a well-organized reference site your agent opens 1.3% of the time. Review it the way you review code.
do · treat CLAUDE.md / AGENTS.md as a reviewed artifact - Make every page carry its own payload.
No cross-reference was followed in their traces, not once. If a constraint matters on a page, write it on that page rather than linking to where it lives. Redundancy across documents is a cost worth paying here.
do · inline the load-bearing detail, do not link to it - If a rule has to hold, make it executable.
A hook, a lint rule, a schema, a test. Keep the sentence for the humans who need the reasoning, and put the enforcement somewhere that can fail. Treat this as posture, not as a proven result: the study measured the absence of validation, it did not measure the fix.
do · convert your top three enforced rules into checks - Give agent working notes a home and a review category.
Decide where plans and logs live, whether they are committed, and who prunes them. A quarter of your agent's documentation traffic goes to files nothing in your process currently owns.
do · add agent notes to the repo hygiene checklist - Keep the reference prose, and write it for humans.
The finding is that agents barely read API references. It is not that references are worthless. Your developers, your vendors, and the person onboarding next quarter still need them. Just stop justifying that spend as an agent-readiness investment.
do · budget human docs and agent docs separately
What this does not license.
The study is observational and its limits are stated plainly by the authors, which is the main reason to trust the parts that do hold. Two public datasets, each dominated by a single agent family, so this is not a survey of how all agents behave. The stage heuristic they use is sticky, so the share of interactions they attribute to debugging is inflated by construction, and they advance only the negative claim that documentation use is not confined to orientation. Tool-call traces are blind to any reading or comparison happening inside the model's reasoning, which means every zero in this note is a zero of observable action, not of thought. Agents that reach files through the shell are undercounted. And it is a measurement of behaviour, not of outcomes: it tells you what agents do, not what they would do better with.
The one extrapolation to watch is the one we flagged at the top. Both datasets are coding agents working in repositories, where an instruction file is a native concept. Whether a customer-support agent or a research agent shows the same 27-to-1 preference is untested. The direction is plausible enough to plan around and thin enough that you should verify it in your own logs before betting a budget on it.
If you are standing up AI agents on your own codebase or workspace and want a second read on the instruction file, the note hygiene, and which of your rules should be a hook instead of a sentence, the contact form is the fastest way in. We will send back a written read on your setup, free.