Coding agents most often turned to repository-local instruction files and working notes, rather than conventional technical documentation or API references, in an observational analysis. Those agent-facing materials accounted for 60.5% of documentation interactions, compared with 10.6% for classical technical documentation and 1.3% for API references.
The study also found that agents produced documentation almost as often as they consulted it. Production occurred at 0.87 times the consultation rate; in a separate pull-request analysis, 41.5% of pull requests changed documentation, and code changes came before documentation changes 4.7 times as often as the reverse.
What the traces show
The analysis covered 557 SWE-chat coding-agent sessions, containing 94,813 development events and 3,033 documentation interactions, alongside 33,097 public AIDev agentic pull requests represented by 690,260 file-level change records.
Researchers tracked repository-local, file-based activity such as discovering, searching, reading, editing and creating documentation. The instrument focused on documentation interactions and the actions surrounding them, rather than on a randomized experiment.
The results did not show a consistent relationship between consulting documentation and then editing code or creating documentation. Code editing had an unadjusted lift of 1.05 but an adjusted odds ratio of 1.33, with an interval from 1.09 to 1.62. Documentation creation had an unadjusted lift of 1.67 but an adjusted odds ratio of 1.41, with an interval from 0.98 to 2.02.
Testing and building were different. Both occurred less often in the action window after consultation than at baseline, and the pattern remained after adjustment for development stage: the adjusted odds ratio was 0.39 for testing and 0.25 for building.
Documentation was usually part of routine work
Most documentation interaction appeared to be self-initiated during ongoing work: 2,129 events, or 70.2% of the total. Failure-driven interaction accounted for 228 events, or 7.5%.
Documentation was the first recovery move in 109 of 2,034 failure episodes, or 5.4%. Among the 11 documentation-first episodes with observable outcomes, 7 were recorded as resolved, a point estimate of 63.6%. But the interval ran from 35.4% to 84.8% and overlapped other strategies, so the authors did not treat the apparent recovery rate as evidence that documentation ranked above them.
The researchers observed no explicit documentation-based validation or escalation sequence under their operational definitions. They cautioned that this does not establish that agents never validate against documentation: such activity could occur inside unobserved reasoning or outside the instrument.
A narrow window on agent behaviour
The study’s conclusions are limited to the repository-local file activity it could observe. The instrument did not capture browser-based documentation, knowledge already present in a model, or documentation embedded in source files; context files were visible only when they were later read or edited explicitly.
The document categories also carry uncertainty. A two-tier path classifier left 54% of documentation events in a residual category at first; language-model labeling covered 500 of 527 distinct ambiguous paths, representing 98.4% of ambiguous events, while 27 paths used keyword fallbacks. The working-notes category had not received human validation.
Because the data were observational, the reported patterns should not be read as proof that documentation consultation caused later testing, building, code editing or documentation creation. The study also does not directly measure documentation quality, code correctness, task success or the effects of changing documentation.
A preprint, not an intervention
The authors describe the results as pointing to two connected parts of documentation work: a recurring consultation process and a production process for creating and updating documentation. They recommend clearer, more correct instruction files and propose executable documentation for future intervention studies, rather than presenting it as a tested solution.
The paper is an arXiv version 1 preprint dated 20 August 2026. Its replication package is described as including four format-specific extractors, a 20-symbol event alphabet, labels for 527 ambiguous paths, an event table covering 3,033 interactions, and code for the bootstrap and GEE analyses, figures and tables.
Paper data and sources
Original title: From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation
Authors: Zhijun Gao, Jing Chen
Journal/Repository: arXiv
Status: Preprint, not yet peer-reviewed
First online: 2026-08-20
DOI: Not available
Original paper · Full text