Your Docs Are for Humans. The Agents Aren’t Reading Them.

The $10B assumption baked into every developer-docs team — that well-structured, actionable, verifiable documentation guides AI coding agents — just got empirically undermined. Two large-scale datasets, 94,000+ development events, and the finding is brutal: agents mostly ignore your docs and talk to themselves instead.

What happened

Researchers Gao and Chen studied agentic workflow behavior across two public datasets: 557 agentic coding sessions (SWE-chat, 94,813 development events) and 33,097 agentic pull requests (AIDev, 690,260 file-level change records). The core finding: 60.5% of all documentation interactions were with agent-facing artefacts — instruction files and working notes — while classical technical documentation captured only 10.6% and API references a rounding-error 1.3%. The assumed causal chain of “agent reads docs → agent edits code → agent runs tests” fell apart under scrutiny: the adjacent transition probability from documentation consultation to code editing is 0.002, and while a stage-adjusted model suggests a modest positive association (OR 1.33 [1.09, 1.62]), the unadjusted signal is nearly flat (lift 1.05). Worse, documentation consultation is actually associated with less immediate testing (lift 0.23; adjusted OR 0.39 [0.25, 0.60]) — the opposite of what “verifiable documentation” advocates preach. Agents also write docs as an afterthought: when both code and documentation change in the same agentic AI pull request, code is touched first 4.7× more often. Documentation consultation is self-initiated 70.2% of the time and failure-driven only 7.5% of the time — agents aren’t running to the docs when things break.

Cold read

This is observational, not experimental — correlation extracted from traces, not a controlled study where doc quality was manipulated and outcomes measured. The “stage-adjusted OR 1.33” for doc-to-edit transitions sounds encouraging, but the unadjusted lift of 1.05 is basically noise, and the authors themselves flag this as “unresolved.” The datasets (SWE-chat, AIDev) reflect today’s agents on today’s tasks — mostly code repair and PR workflows — which may be unusually doc-light compared to greenfield development or onboarding scenarios. “No explicit documentation-based validation sequence was observed” is a striking negative result, but absence of observation in these traces doesn’t prove agents can’t use docs for validation when prompted or architected to do so. The “two-lobed cycle” descriptive model is a post-hoc narrative fit to behavioral traces, not a mechanistic theory of how agent memory and retrieval interact.

What it means for you

• Signal maturity: 2/5 — empirically grounded but observational; causal claims remain unproven
• Who gets hurt: Developer-tools companies and DevRel teams who’ve bet engineering hours on “agent-optimized” documentation standards (think llms.txt evangelists and structured-docs startups selling the dream of machine-readable API references)
• What breaks if this is true: The ROI case for investing in human-readable and machine-readable technical documentation collapses — agents are generating their own working notes and ignoring the corpus you spent quarters building
• Why it might not land: Agent architectures are evolving fast; a study on 2024-era agents may not describe 2026 agents with richer context windows and explicit retrieval steps baked into their scaffolding
• Watch for: Whether major coding-agent vendors (Cursor, GitHub Copilot Workspace, Devin successors) ship explicit doc-retrieval steps as required pipeline stages — if they do, this paper’s behavioral baseline becomes obsolete quickly

Forecast as of 2026-08-21

By Q3 2027, at least two major developer-tools vendors will publicly deprioritize or reframe “agent-optimized documentation” as a product feature — citing agent behavioral data — while the llms.txt standard will remain niche (under 5% adoption among Fortune 500 engineering orgs), consistent with agents continuing to self-generate working context rather than consuming pre-authored docs.

Source: From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation — Zhijun Gao, Jing Chen. https://arxiv.org/abs/2608.20195v1