从 Agent 行为到 Agent 友好型文档：关于编码 Agent 如何发现、阅读和编写技术文档的实证研究

技术文档是为人类开发者编写的，但如今越来越多的软件变更由自主编码 Agent 完成。它们会查阅哪些文档、何时查阅以及随后会发生什么，仍然未知。我们基于行为，对 Agent 与文档的交互进行了研究，涵盖两个公开数据集：来自 SWE-chat 的 557 个 Agentic 编码会话，产生了 94,813 个开发事件，其中包括 3,033 次文档交互；以及来自 AIDev 的 33,097 个 Agentic pull request，包含 690,260 条经分类的文件级变更记录。四项发现对当前文档实践提出了挑战。首先，Agent 的文档工作主要由面向 Agent 的工件主导：指令文件和工作笔记占所有文档交互的 60.5%，而传统技术文档占 10.6%，API 参考占 1.3%。其次，查阅与代码编辑之间的关联尚无定论：相邻转移概率为 0.002，未调整的三事件提升度为 1.05，而按阶段调整的模型将其置于大于 1 的水平（OR 1.33 [1.09, 1.62]）；文档创建在未调整情况下有所升高（提升度 1.67），但其调整后的区间包含 1。第三，未观察到明确的基于文档的验证序列，并且查阅与较少的即时测试相关（提升度 0.23，聚类 CI 0.08-0.45；调整后 OR 0.39 [0.25, 0.60]）。第四，查阅更多是自发启动的（70.2%），远多于由失败驱动的（7.5%），并且文档滞后于代码：在同时更改二者的多提交 pull request 中，代码先被触及的频率高出 4.7 倍。基于这些轨迹，我们推导出一个 Agent-文档交互的描述性模型，将其视为一个双叶循环，而非线性旅程，并表明“Agent 友好型”文档的两个被广泛假定的属性——可操作性和可验证性——缺乏一致的行为支持。我们发布了我们的流水线、编码方案和事件级数据。