The "agent-friendly documentation" push is aimed at the wrong artefact.

The "agent-friendly documentation" conversation is aimed at the wrong artefact. Real coding agents don't consume documentation the way new engineers do. They consume their own working notes.

In a recent empirical study of 557 agentic coding sessions and 33,097 agentic pull requests, instruction files and working notes absorbed 60.5% of all documentation interactions. Classical technical documentation pulled 10.6%. API references pulled 1.3%. The leverage point isn't polished prose on a docs site. It's the scratchpad the agent already keeps.

The two-lobed cycle is the cleaner reframe. Agents consult first, mostly self-initiated at 70.2% rather than failure-driven at 7.5%, and edit code rather than text: among multi-commit pull requests changing both, code is touched first 4.7 times more often than documentation. The category worth designing for isn't "actionable" or "verifiable" prose. Those properties lacked consistent behavioral support in the data. The category is the agent's own instruction file, organized around consult-then-edit and structured so the next session can find the working note that worked.

The redirect is concrete. SDK maintainers, internal platform teams, and open-source authors should treat the agent's instruction files and working notes as the primary surface; the rest is annotation. Honest caveat from the study: 60.5% measures interaction volume, not effectiveness. An agent that consults one good reference and acts correctly can still beat one that re-reads its scratchpad sixty times. The category holds. The priority order is what changes.