From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation

Source

• Source name: arXiv
• Source kind: paper
• Authors / organization: Zhijun Gao, Jing Chen
• Venue: arXiv: cs.SE
• Published: 2026-08-20
• Collected: 2026-08-21
• URL: http://arxiv.org/abs/2608.20195v1
• PDF: https://arxiv.org/pdf/2608.20195v1
• DOI: UNKNOWN
• Registry group: academic_apis_and_preprints
• Evidence role: canonical_academic_index
• Language: en
• Country / region: UNKNOWN

Plain-Language Brief

Researchers studied how autonomous coding agents interact with technical documentation by analyzing two datasets. They found that agents primarily work with internal documents like instruction files and notes rather than traditional technical documentation or API references. The link between consulting documentation and code editing is weak, and there's no observed explicit validation sequence. Most consultations are self-initiated, and documentation trails code changes. The study suggests a cyclical model of agent-documentation interaction and questions the assumption that 'actionable' and 'verifiable' documentation is beneficial for agents.

What the Document Says

• Researchers analyzed two datasets: SWE-chat and AIDev, containing coding sessions and pull requests by autonomous agents.
• The study found that instruction files and working notes accounted for 60.5% of all documentation interactions.
• Traditional technical documentation and API references made up only 10.6% and 1.3%, respectively, of documentation interactions.
• There is an unresolved link between consultation and code editing with a probability of 0.002 and an unadjusted three-event lift of 1.05.
• A stage-adjusted model places the link above unity (OR 1.33 [1.09, 1.62]).
• Documentation creation is elevated but its adjusted interval includes unity.
• No explicit documentation-based validation sequence was observed.
• Consultation is associated with less immediate testing (lift 0.23).
• Self-initiated consultations outnumber failure-driven ones (70.2% vs 7.5%).
• Documentation trails code changes: among multi-commit pull requests, code is touched first 4.7x more often.
• The study suggests a descriptive model of agent-documentation interaction as a two-lobed cycle rather than a linear journey.
• Two assumptions about 'agent-friendly' documentation - actionability and verifiability - lack consistent behavioral support.

Key Concepts Mentioned

• autonomous coding agents
• technical documentation
• SWE-chat
• AIDev
• consultation
• code editing
• validation sequence
• self-initiated consultations
• documentation trails code changes
• two-lobed cycle
• actionability
• verifiability

Claims Made by the Document

• Agents primarily work with internal documents.
• The link between consultation and code editing is weak.
• There's no observed explicit validation sequence.
• Consultation is self-initiated far more often than failure-driven.
• Documentation trails code changes.

Evidence Used

• Analysis of two datasets: SWE-chat and AIDev.

Methods / Approach

• Behavior-grounded study
• Analysis of coding sessions and pull requests

Limitations Stated by the Authors

UNKNOWN

Limitations Noted by the Agent

Agent interpretation — not from the source.

UNKNOWN

Open Questions

UNKNOWN

Notes for Future Q&A

May include interpretation. Labeled where it does.

UNKNOWN

Raw Abstract / Excerpt

Technical documentation is written for human developers, but an increasing share of software changes is now authored by autonomous coding agents. Which documents they consult, when, and what follows remain unknown. We conduct a behaviour-grounded study of agent-documentation interaction across two public datasets: 557 agentic coding sessions from SWE-chat, yielding 94,813 development events including 3,033 documentation interactions; and 33,097 agentic pull requests from AIDev, with 690,260 classified file-level change records. Four findings challenge current documentation practice. First, agents' documentation work is dominated by agent-facing artefacts: instruction files and working notes account for 60.5% of all documentation interactions, versus 10.6% for classical technical documentation and 1.3% for API references. Second, the link between consultation and code editing is unresolved: the adjacent transition probability is 0.002 and the unadjusted three-event lift 1.05, whereas a stage-adjusted model places it above unity (OR 1.33 [1.09, 1.62]); documentation creation is elevated unadjusted (lift 1.67) but its adjusted interval includes unity. Third, 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]). Fourth, consultation is self-initiated (70.2%) far more often than failure-driven (7.5%), and documentation trails code: among multi-commit pull requests changing both, code is touched first 4.7x more often. From these traces we derive a descriptive model of agent-documentation interaction as a two-lobed cycle rather than a linear journey, and show that two widely assumed properties of 'agent-friendly' documentation - actionability and verifiability - lack consistent behavioural support. We release our pipeline, coding scheme, and event-level data.