If you've ever tried rewriting your company's API documentation or cleaning up a Notion ops manual, you've probably paused at the same question: how do you write it so that an AI coding tool like Claude Code will actually reference it on its own? For solo founders and product managers running a service without a developer on staff, this question feels especially urgent. The more you hand off coding work to an AI agent, the more the documentation you leave behind becomes that agent's only guide.
Yet until now, no study had actually looked at behavioral data to see which documents AI coding agents open, when they open them, and what they do next. A paper by Zhijun Gao and Jing Chen sets out to fill that gap. Advice on how to write good documentation is already abundant, but the researchers' starting point is that none of it has been checked against how agents actually behave.
Measuring How Agents Actually Consume Documentation
The researchers dug into two publicly available datasets. The first, SWE-chat, contains 94,813 development events drawn from 557 agentic coding sessions, of which 3,033 were document-related interactions. The second, AIDev, holds 690,260 file-level change records from 33,097 agentic pull requests. Because both datasets capture AI agents actually writing code as it happened, the researchers could observe agent behavior directly rather than infer it. They examined, one by one, what kinds of documents agents open, whether that reference leads to code edits or tests, and which changes first — the docs or the code.
Code Moves Before Documentation Does
The first thing that stands out is exactly which documents agents actually open most. Instruction files and working notes accounted for 60.5% of all document interactions, while traditional technical documentation — the kind people usually picture — made up just 10.6%, and API references only 1.3%. In other words, agents reach for a short instruction telling them what to do right now far more often than they reach for a polished guide.
The relationship between reading documentation and editing code turned out to be less straightforward than expected. The probability that a document reference was immediately followed by a code edit was just 0.002, and the raw association was weak too (a 3-event lift of 1.05). Once the model controlled for stage, though, the odds of an edit following a reference rose significantly (OR 1.33, 95% CI 1.09–1.62). By contrast, document references were actually less likely to be followed immediately by testing (lift 0.23, adjusted OR 0.39) — suggesting that reading documentation seems to substitute for verification rather than lead to it.
An even more interesting finding concerns which changes first, the documentation or the code. Agents overwhelmingly reached for documentation because they judged it necessary on their own — 70.2% of the time — rather than because they'd hit a failure, which prompted a lookup only 7.5% of the time. And in multi-commit pull requests that touched both code and docs, code was edited first 4.7 times more often than documentation was.
Code First, Docs Later
Based on these results, the researchers describe the relationship between agents and documentation not as a linear journey but as a two-lobed cyclical structure. Rather than a straight line — read the docs, then write the code — code work and documentation work move on different rhythms and loop back on each other.
How to Write Documentation AI Agents Will Actually Use
For a solo founder or product manager, the first thing worth fixing isn't the API reference or the long-form guide — it's a short instruction file that spells out what should and shouldn't be done in this project right now. That's exactly the kind of document agents actually open most often. It's also worth remembering that a carefully written API doc, by comparison, gets referenced relatively rarely.
Another thing worth keeping in mind: no matter how well you write your documentation, an agent reading it doesn't automatically mean it will run tests. If a task genuinely requires verification, it's safer to leave an explicit instruction — separate from the documentation itself — telling the agent to run tests after this kind of work. Documentation and code don't update themselves in tandem either, so it's worth building the habit of separately asking the agent to update related docs after code changes.
What This Study Doesn't Tell Us
This study observed behavior recorded in two public datasets; it did not experimentally vary documentation formats to compare their effects. The researchers also note that two properties commonly assumed in advice about writing agent-friendly documentation — that it should be executable and that it should be verifiable — were not consistently supported by the actual behavioral data. The honest takeaway, then, is not to treat these findings as a formula guaranteeing agents will read your docs better, but to use them as grounds for re-examining conventional wisdom.
