代码生成时代的文档生存困境：AI编码代理的阅读与写作行为实证分析
从人类阅读到机器阅读：文档消费范式的根本重塑
在软件工程的演进历程中，技术文档始终扮演着“导图”和“参考手册”的角色，专为人类开发者编写。然而，随着大模型和自主代理的崛起，软件变更的来源已不再仅仅是人类键盘敲击的结果。近期的一项跨数据集实证研究打破了这一常识，揭示了AI编码代理与技术文档之间微妙而又冷漠的互动图景。研究并非浅尝辄止，而是基于两个维度的海量数据：SWE-chat数据集中557个代理编码会话，涉及94,813个开发事件；以及AIDev数据集中33,097个代理拉取请求，包含690,260条分级文件变更记录。这组数据的规模和精度，为我们重新审视“文档对AI有用”这一命题提供了坚实的基石。
文档的冷门地位：60.5%的注意力集中在“非技术性”材料上
研究的第一个也是最震撼的发现，直接冲击了业界对文档价值的预设。在所有文档交互中，指令文件和工作笔记占据了60.5%的份额，而传统的技术文档仅占10.6%，API参考文档更是惨淡的1.3%。这一数据背后，折射出的是代理的阅读习惯并非来源于对问题的深入探究，而是被“即时可用”的指令集所主导。对于人类开发者而言，README、CONTRIBUTING.md以及各类配置文件往往是项目入门的第一道门槛；但对于代理来说，这些文件是完成任务的“速查表”。这种消费模式的转移，意味着传统的技术文档正在失去作为“知识载体”的核心地位，取而代之的是一系列零散、功能化的配置说明。
咨询与行动的断裂：文档阅读的“安慰剂”效应
或许更值得深省的是，文档的阅读与实际的代码修改之间存在着一种近乎尴尬的“概率断层”。研究指出，相邻的转换概率仅为0.002，未经调整的三事件提升因子仅为1.05，几乎可以视为统计学上的无意义。即便采用阶段调整模型，关联性也仅勉强突破 unity， odds ratio 为 1.33 [1.09, 1.62]。这意味着，代理咨询文档后，转而进行代码编辑的可能性并不比随机高多少。更有趣的是，文档的创作虽显示出未经调整的提升因子 1.67，但在调整后的区间中再次跌入 unity 范围内。更令人意外的结果是，文档咨询与即时测试的关联性极低，提升因子仅为 0.23，调整后的 odds ratio 更是降至 0.39 [0.25, 0.60]。这几乎可以断言，阅读文档并不会让代理更倾向于立即进行验证，文档似乎成了一种“安慰剂”，让代理在阅读中产生了虚假的进展感，而非推动实际的测试与修正循环。
自主驱动的咨询：代理的“主动权”在哪里
关于咨询的发起动机，研究通过细致的事件分类揭示了另一层面的真相。咨询行为中有 70.2% 是自主发起的，而仅有 7.5% 是由失败或错误触发的。这表明，代理并非在“求救”，而是在“探索”。代理主动查阅文档，往往是为了确认路径或获取灵感，而非在遇到死胡同时寻求救援。此外，在多提交的拉取请求中，代理倾向于先触碰代码，再关联文档。代码与文档的触发顺序呈现出明显的“代码优先”逻辑，文档往往成为事后的补充或注解。这种“代码为王，文档为辅”的行为链条，再次证明了当前文档体系在代理工作流中的边缘地位。
“双峰模型”：重新定义 AI 友好的文档标准
基于上述行为痕迹，研究者构建了一个“双峰循环”模型，用以替代传统的“线性旅程”假设。在这个模型中，代理的工作流不再是文档-代码-测试的单向流动，而是在“指令导向的配置调整”与“代码实验的实证验证”之间反复横跳。值得一提的是，研究特别审视了业界普遍推崇的“AI友好型”文档两大支柱：可操作性和可验证性。然而，实证数据并未为这些属性提供一致的行为支持。代理关注的并非文档是否易于验证，而是文档是否能快速指引下一步的行动。这实际上暴露了当前文档标准与代理实际需求之间的错位：我们花费大量精力去润色文档的语言结构和验证流程，而代理实际上只需要一份能被快速“消化”并驱动下一步任务的指令集。
前瞻：从“人文文档”向“代理友好”文档的转型
展望未来，软件文档的演进必然将被迫向着更适应代理消费的方向转型。这并不意味着传统的技术文档将彻底消亡，但其角色定位将发生质的飞跃。未来的文档体系可能需要兼具两套特性：一方面保留人类阅读所需的结构化叙事和深度解析；另一方面，提供精简、结构化、机器可解析的“代理视角”入口。或许，我们需要重新定义文档的边界——不再仅仅是知识的堆砌，而是成为代理与代码交互的协议接口。对于文档编写者和维护者而言，这场由AI驱动的范式重塑，既是挑战，也是重新审视文档价值的契机。技术文档的未来，或许不再是给人看的，而是给机器用的“作业指南”。