What Coding Agents Actually Read — Instruction Files, Not Your Documentation (2026)

Instruction files are the dominant documentation surface

Broken down, the 60.5% is two categories. Agent instruction files are "the most frequently used document type (1,074 events, 35.4%)" and "are among the most frequently changed files in agentic pull requests." Agent working notes — plans, thoughts/ directories, verification logs — account for 25.1%.

Against that, API references get 40 events, 1.3% of documentation interactions. The paper's own summary of the gap: instruction files receive roughly 27 times as many interactions as API references.

The recommendation the authors draw is narrow and practical: "For projects allocating finite documentation resources to support agentic contributors, this difference suggests prioritising the correctness and clarity of instruction files." Not "stop writing API docs" — those serve humans and tools this study didn't observe. Just that if you're deciding where an hour goes for the benefit of agents, AGENTS.md is where the traffic is.

Agents don't follow your links

This one quietly undermines advice almost every tool gives. "Documentation reads are frequently followed by further reads (transition probability 0.270), whereas Follow-reference is entirely unattested."

Entirely unattested means zero observed instances of an agent traversing a reference from one document to another. The authors' conclusion is carefully hedged: "This pattern motivates studying self-contained documents with locally retrievable structure, rather than assuming that agents navigate richly cross-linked documentation. It does not, however, establish that link hygiene has no behavioural consequences."

Worth sitting with if your instruction files are mostly pointers. "See docs/architecture.md for the reasoning" may be a well-formed sentence that nothing acts on.

Consulting documentation is decoupled from editing code

Here the paper is scrupulous about its own uncertainty, and the honest summary is that the coupling is unresolved rather than absent. The adjacent transition probability from a documentation read to a code edit is 0.002. The unadjusted three-event lift is 1.05 — essentially nothing. A stage-adjusted model puts it above unity, at OR 1.33 [1.09, 1.62]. Documentation creation runs the other way: elevated unadjusted at lift 1.67, but "its adjusted interval includes unity." As the authors put it, "Neither connection is consistent across specifications."

So agents read, and then mostly they reason or read again. The strongest transition inside the consultation lobe is a read back to itself at 0.270 (CI 0.232–0.307); its strongest outgoing move is to reasoning at 0.245 (CI 0.205–0.295).

Nobody validates against documentation, and consulting it correlates with less testing

"No explicit documentation-based validation sequence was observed, and consultation is associated with less immediate testing (lift 0.23, cluster CI 0.08–0.45; adjusted OR 0.39 [0.25, 0.60])." Elsewhere, flatly: "zero validation events."

That's a correlation in observational data, not a causal claim, and the authors make none. But it means the popular idea that documentation should be written so an agent can check its work against it describes something that didn't happen here at all.

Agents read documentation because they chose to, not because they're stuck

Consultation is self-initiated 70.2% of the time and failure-driven only 7.5%; documentation feeds back into the consultation lobe in just 5.4% of failure episodes. And documentation trails code rather than leading it: "among multi-commit pull requests that change both, code is touched first 4.7 [times] more often than documentation."

The authors' own explanation is the interesting part

Having found a loop that doesn't match how the literature describes human developers, they offer two candidate mechanisms and decline to pick:

"Agents may externalise reasoning to files because their context windows are bounded, making documentation a form of working memory rather than a reference; the prominence of plans and thoughts/ directories is consistent with this possibility. Alternatively, they may not validate against prose because a cheaper oracle, the test suite, is invoked directly. In either case, we did not observe prose functioning as a specification."

That single hypothesis reframes the whole 60.5%: a large share of what agents "read" may be notes they wrote themselves ten minutes earlier, because there was nowhere else to put them. Which produces a problem nobody has tooling for. "Plans, thoughts/ directories, and verification logs accumulate in repositories as durable artefacts. Repository hygiene tooling, code review checklists, and documentation quality metrics currently have no category for them."

Getting the boundary right matters more than the headline, and this paper's own limitations section is unusually direct.

The 60.5% is a share of documentation interactions, not of everything agents read. The denominator is 3,033 documentation interactions out of 94,813 development events. It is not "60.5% of what an agent reads." Anyone quoting it as a share of total agent activity has changed the claim.

A quarter of that figure is explicitly provisional. This is the caveat that most secondhand summaries drop, and the authors put it in writing: "The agent_working_note category — 25.1% of documentation events, and one of our headline findings — rests on language-model classification of 500 ambiguous paths (98.4% of ambiguous events), with 27 paths falling back to keyword rules. No human validation of these labels has been performed... Until then, the precise share of this category should be treated as provisional." They add that the qualitative finding is sturdier than the number: agent-authored working documents are "a large and previously uncategorised class," visible in the raw paths, whatever the exact percentage.

The absolute rates are lower bounds. "Documentation is identified by file path. Docstrings, inline comments, and prose embedded in source files are invisible to our instrument." Projects favouring in-source documentation are underrepresented, and the authors say so.

Why agents read anything was not measured. "Purpose is not measured... by design, we do not analyse agents' reasons for reading particular documents." The study reports trigger, interaction type, and outcome, not intent.

It's observational, so nothing here says changing your docs changes behaviour. On actionability specifically: "these analyses provide no consistent behavioural evidence for the coupling, and our observational design cannot show that improving actionability changes behaviour."

The authors decline the most quotable comparison available to them. "We explicitly decline to conclude that documentation-based recovery is more effective, despite it having the highest point estimate (63.6%). With observable outcomes for only 11 episodes, the interval spans 35.4–84.8% and overlaps every alternative." That's a research team leaving a good headline on the table, and it's why the rest is worth trusting.

And it sits alongside work pointing in other directions. Other 2026 studies measured the performance effect of context files and found it weak or negative; a separate line measured gains from curated retrieval that scale with model capability — the ground in how much memory you should give an AI agent. This paper measures neither; it measures behaviour. Reconciling the two is open work, and a paper from two days earlier argues our measurement discipline isn't ready for it — discussed in does agent memory actually improve performance.

MemoryLake was not part of this study. Nothing here evaluates a memory layer, ours or anyone's.

"Agents ignore your instruction files." The opposite of what it found. Instruction files are the most-read documentation surface by a wide margin. What's weak is the link between reading and the next action — a different claim, and the distinction we've drawn before in why agents ignore the instruction files you wrote: loading is not following. This paper sharpens it. They load, they're read heavily, and reading still doesn't reliably determine behaviour.

"So documentation doesn't matter." The paper says two specific claims lack behavioural support in this corpus — actionability and verifiability. It doesn't say documentation is useless, and it explicitly recommends investing in the correctness of instruction files.

"Agents read docs when they get stuck." 7.5% failure-driven. The belief the trigger distribution most directly contradicts.

"Cross-linking is pointless." Follow-reference was unattested in these traces, and the authors decline to conclude that link hygiene has no consequences. Those are different statements.

"This proves agents need a memory system." It proves nothing of the sort. It observes that agents write files resembling working memory, and offers that as one of two candidate explanations for a behavioural pattern.

If the working-memory hypothesis is right, then a share of those thoughts/ directories and plan files is an agent doing memory management with the only tool it has: your git repository. Nothing in your review process has a category for those files. Three things follow.

Audit what's accumulating. Search your repo for plan files, thoughts/ directories, and agent-created verification logs. Decide, per directory, whether each is a durable artefact or scratch. Most teams find they've been committing both without noticing.

Invest the instruction-file hour where the traffic is. Correctness and clarity there pay better than the same effort on an API reference an agent opens 1.3% of the time. And since Follow-reference was unattested, prefer self-contained statements over pointers for anything that must land.

Separate steering from remembering. An instruction file is always-on and capped by every tool that reads it, so durable knowledge — decisions, constraints, rejected approaches — is squeezed out first. Then an agent reconstructs it by writing a plan file.

That last one is what MemoryLake is for: memory as entries you can read, correct, and delete, queried when relevant rather than committed to your repository as a side effect. Setup is three steps.

Step 1: Create an API key

Sign in to MemoryLake and create an API key. One credential across the tools you connect.

Step 2: Upload your first memories

Short entries, one claim each. Write the material that currently ends up in a plan file or nowhere:

Decisions with the constraint that forced them. The category an instruction file states as a rule and drops the reason for.

Approaches already rejected here, and why. Written rejections are what stop a fresh session re-deriving them — and re-deriving is exactly the work those thoughts/ files record.

Environmental facts nothing announces. The test that only fails in CI, the undocumented rate limit, the ordering requirement between two migrations.

Corrections you've given more than once. If a person had to say it twice, it belongs somewhere retrievable rather than in a conversation that ended.

Step 3: Connect your AI & agents

Connect the tools you use. MemoryLake is reachable over MCP and over an API, so MCP-native agents — Claude Code, Codex, and OpenClaw among them — connect by pointing at the MCP server, while other assistants read the same memory through the API. What you retrieve doesn't inflate the always-on instruction file, and it doesn't land in your commit history.

Three honest limits, and the first is the point of this article. MemoryLake was not part of this study and this paper is not evidence that a memory layer changes agent behaviour — the design is observational, and the authors are explicit that it cannot show that improving documentation changes what agents do. It holds only what you or your agents write into it. And it doesn't clean up your repository: auditing the plan files an agent already committed is a manual job.

Instruction files graduate to first-class documentation. They're the most-read surface, and in most repos get less review than a README.

Agent-authored notes become a review category. Right now they have none — no hygiene tooling, no checklist line, no staleness metric.

Pointers stop being a substitute for content. Follow-reference was unattested. If a constraint matters, state it where it's needed.

Documentation stops being your failure-recovery plan. Agents consult it proactively, not when stuck — so it's closer to orientation than a manual, and should read that way.

Put your best hour into the instruction file. It's the most-read document type in the corpus by a factor of roughly 27 over API references.

Make each statement self-contained. No traversal of references was observed. Assume the reader stops at the file it opened.

Give agent working notes a home and a lifecycle. Decide what's durable, what's scratch, and what should never have been committed.

Don't rely on documentation as a verification surface. Zero validation events were observed. Tests are the oracle agents actually reach for.

Keep reasoning out of always-on files — every tool caps them and the reasoning is cut first, the problem in why RAG isn't memory — and consolidate scattered notes into something queryable, the shape of turning project docs into AI memory.

Treat single-corpus behavioural findings as provisional. Two datasets, path-identified documentation, one working-note category the authors label unvalidated. Useful, not settled.

What do coding agents actually read? On the evidence of 557 sessions and 33,097 pull requests: overwhelmingly, the files written for them. Agent instruction files and agent working notes make up 60.5% of documentation interactions, classical technical documentation 10.6%, API references 1.3%.

But the sequence matters more than the share. Agents consult documentation on their own initiative rather than when stuck, circle within reading and reasoning rather than moving to code, never traverse a reference to another document, and were never observed validating their work against prose. The authors' own reading is that a good deal of this may not be reference-seeking at all — that bounded context windows push agents to externalise reasoning into files, "making documentation a form of working memory rather than a reference."

If that's right, the practical conclusion isn't "write better docs." It's that your repository has quietly become an agent's scratchpad, with no review process that knows it. Invest in the instruction file, because that's where the reads are. Make statements self-contained, because nothing follows your links. And give the durable knowledge — decisions, constraints, approaches already ruled out — a home that isn't an always-on file with a byte cap or a thoughts/ directory nobody reviews.