研究编码智能体如何查找、阅读和编写技术文档，发现其行为与人类预期差异巨大。
From Agent Behaviour to Agent-Friendly Documentation: An Empirical Study of How Coding Agents Discover, Read, and Write Technical Documentation
- 通过真实编码会话数据，分析智能体与文档的交互模式。
- 60.5%的文档查阅集中在指令文件和工作笔记，而非传统技术文档。
- 智能体多主动查阅文档，且代码修改常先于文档更新，适合优化文档设计者参考。
技术文档本为人类开发者编写，但越来越多的软件修改由自主编码智能体完成。它们在何时、为何查阅哪些文档仍不明确。本研究基于两个公开数据集：557个来自SWE-chat的智能体编码会话（含94,813次开发事件，3,033次文档交互）和33,097个来自AIDev的智能体拉取请求（含690,260条文件级变更记录），展开行为实证研究。四项发现挑战现有文档实践：第一，智能体文档交互中60.5%针对面向智能体的文档（如指令文件、工作笔记），而经典技术文档仅占10.6%，API参考仅1.3%；第二，查阅与代码编辑的关联性不强（相邻转移概率0.002，三事件未调整提升1.05），但阶段调整模型显示文档创建与后续动作正相关（比值比1.33 [1.09, 1.62]）；第三，未观察到基于文档的显式验证流程，查阅反而伴随更少即时测试（未调整提升0.23，聚类置信区间0.08–0.45；调整后比值比0.39 [0.25, 0.60]）；第四，70.2%的查阅为自发起始，远高于因失败触发的7.5%，且在多提交拉取请求中，代码修改先于文档更新达4.7倍。由此构建出双叶循环式交互模型，表明“可操作性”与“可验证性”等所谓‘智能体友好’特性缺乏行为支持。研究开源了分析管道、编码方案与事件级数据。
原文摘要 · Abstract (English)
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.
Thank you to arXiv for use of its open access interoperability. PaperDance 不是 arXiv 官方产品；中文卡片由大模型生成，请以原文为准。