From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation
编码Agent读文档行为:主流假设缺乏行为支撑:对557次Agent编码会话(94,813事件含3,033次文档交互)和33,097条Agent PR(690,260文件变更)进行行为分析,发现60.5%文档交互指向自身产出物(指令文件+工作笔记),API参考仅1.3%;读文档→写代码相邻转移概率0.002;未观测到任何文档驱动的验证序列。
现行「agent-friendly文档」指南假设文档应具备可执行性与可验证性,本研究在两个公开数据集上追踪Agent真实文档交互行为以检验该假设。在94,813个事件中,60.5%文档交互指向指令文件和工作笔记,读文档→写代码相邻转移概率仅0.002,且从未出现文档驱动的验证序列。
Agent主导的文档类型是指令文件和工作笔记(60.5%),而非API参考(1.3%);读文档→写代码的行为链路极弱(相邻概率0.002),且从未观测到文档驱动验证序列,「可执行性」与「可验证性」两大设计假设缺乏行为支撑。
1. 现行「agent-friendly文档」建议(清晰标题、可运行示例、llms.txt)基于对Agent应如何行为的推断而非观测;API参考主导了现有文档工程工具链,但在实际Agent交互中仅占1.3%,与指令文件和工作笔记(60.5%)存在系统性偏差。 2. 从SWE-chat(557会话、94,813事件)和AIDev(33,097 PR、690,260文件变更)中恢复文档事件并编码为14类类型,计算相邻转移概率、三事件lift及PR时序比;阶段调整逻辑回归控制会话阶段混淆,通过对比非调整与调整估计量评估混淆程度。 3. 读文档→写代码相邻概率仅0.002(调整OR 1.33 [1.09, 1.62],区间上界有限);读文档→测试lift 0.23(调整OR 0.39 [0.25, 0.60]),读文档与测试负相关;代码先于文档变更4.7倍;语料中零例文档驱动验证序列,「可验证性」设计假设无行为依据。
SWE-chat:557次Agent会话、94,813个事件、3,033次文档交互,56.7%的会话含文档交互。AIDev:33,097条PR、690,260条文件变更,41.5%的PR涉及文档变更。文档类型分布:指令文件35.4%、工作笔记25.1%、经典技术文档10.6%、API参考1.3%、故障排查0.4%。关键量:读文档→代码相邻概率0.002;三事件非调整lift 1.05,阶段调整OR 1.33 [1.09, 1.62];读文档→测试lift 0.23(CI 0.08–0.45),调整OR 0.39 [0.25, 0.60];文档创建非调整lift 1.67但调整区间含1;自主发起咨询70.2%,失败驱动7.5%;代码先于文档变更4.7倍。
- 它要解决什么
- 自主编码Agent实际以何种方式、在何时机与哪类文档交互?「读文档→写代码」和「文档用于验证代码」两项行业假设是否有行为支撑?
- 研究路径
- 构建事件提取流水线,从四种异构Agent转录格式中恢复文档事件并编码为14类类型;计算相邻转移概率(单步)和三事件lift(多步);对PR中代码与文档文件变更分别排序后比较首次出现时序;以聚类标准误和阶段调整逻辑回归区分混淆效应与真实关联。
- 这对工程意味着什么
- 优先维护Agent指令文件并保持其准确,而非扩充API参考——Agent自主咨询指令文件的比例(35.4%)是API参考(1.3%)的27倍。应避免将「文档驱动验证」纳入系统设计假设,该行为在本语料中从未出现,且读文档后测试活动反而降低。
- 证据定位
- 读文档→写代码相邻转移概率0.002,三事件非调整lift 1.05,阶段调整OR 1.33 [1.09, 1.62];读文档与测试负相关(lift 0.23,调整OR 0.39 [0.25, 0.60]);指令文件+工作笔记占60.5%,API参考仅1.3%。(筛选维度:可复核评测、软件工程方法)
- 适用边界
- 两个数据集均来自开源仓库,不覆盖闭源或企业环境;事件提取依赖四种异构转录格式,格式间召回率差异未完全量化;为描述性研究,无受控实验设计,相关关系不能推断因果方向。
方法与英文摘要
从SWE-chat提取557次Agent会话得94,813个开发事件(含3,033次文档交互);从AIDev提取33,097条Agent PR,分类690,260条文件变更记录。将文档事件编码为14类类型,计算相邻转移概率和三事件lift;以聚类置信区间和阶段调整逻辑回归控制会话阶段混淆;并按代码与文档分别排序PR提交时序以判断方向。
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.