北卡州立大学实测732次，过期文档让CodingAgent默默承担「文档债」利息

在AI编程代理（Coding Agent）日益普及的今天，一个隐蔽却普遍的问题正悄然积累成本：过期的文档指令正在让每个新会话为历史遗留问题“付利息”。北卡罗来纳州立大学（NCSU）一项严谨的实证研究揭示了这一现象——研究人员对真实开源仓库中的过期指令文件进行732次受控实验，发现Agent在任务执行中会无意识地重复执行已失效的命令、访问已迁移的路径或沿用已被废弃的流程，而整个过程既不报错也不修正，仅以增加工具调用次数和token消耗为代价“绕过去”，最终任务仍能成功。这种隐性开销被研究者定义为“文档债”（documentation debt），其利息藏在每一次看似流畅的交互背后。

这项研究的核心价值在于它没有构造人工冲突，而是从GitHub上严格筛选出三个真实存在的过期指令案例，覆盖三种典型场景：

• 命令案例（pyflow，Python）：AGENTS.md 中仍写着 pytest tests/ifds，但测试目录早在2026年7月就迁至 tests/analysis/ifds；此后该文件又经历两次编辑，该行指令始终未更新。
• 位置案例（cog，Python）：指令指向的 base_predictor.py 在2026年2月被合并入其他文件，后续13次文件修改均未同步更新该引用。
• 流程案例（aghub，Rust）：CLAUDE.md 要求在 crates/core/src/agents/ 下新建组件文件，而该目录已于2026年3月迁移，后续4次编辑仍未修正。

值得注意的是，这些过期指令并非因项目停滞而被遗忘，恰恰相反，它们存在于活跃维护的仓库中——每次代码变更都“顺路”经过了指令文件，却无人执行核对或清理。这反映出一种普遍现象：开发者倾向于向文档“加料”，而非做减法或验证；文档更新滞后于代码演进，成为技术债务的一种隐形形态。

为量化影响，研究团队设计了极简而严谨的对照实验：针对同一真实bug修复任务（由历史修复回放或条件反转生成），仅改变指令文件中关键一行的状态，其余完全一致。三种处理方式分别为：

实验在Claude Code环境中运行，使用Claude Haiku 5.5与Sonnet 5.5两个模型，共22个任务 × 3种条件 × 5–7次重复 = 732次独立运行，全部在隔离容器中完成，确保环境一致性。评判标准分为两层：结果层面看bug是否真正修复（通过离线运行完整测试套件验证）；过程层面则记录所有工具调用细节，包括是否触碰过期路径、总调用次数、token消耗，并辅以人工编码分析agent行为轨迹。

• Stale组：Agent先尝试运行 pytest tests/ifds，失败后转而搜索并定位到新路径 tests/analysis/ifds，最终执行成功；
• Corrected组：直接运行新路径命令，一步到位；
• Removed组：Agent自行推断测试位置，路径探索路径更长，但未依赖过期信息。

关键数据对比显示：Stale组平均多触发1.8次工具调用，token消耗高出约12%，且存在“虚假成功”现象——某些工具调用返回“OK”状态码，实则因路径不存在而未执行任何有效操作，却被Agent误判为成功。

更值得警惕的是，这种成本在现有评测体系中完全不可见。主流评估聚焦于最终任务是否达成（pass/fail），而忽略中间过程效率。研究指出：“只看通过率的评测，对这笔债完全失明。”这意味着大量生产环境中部署的Coding Agent可能正持续支付隐性成本，尤其在高频调用、长会话或复杂项目中，累积效应不容忽视。

该研究还揭示了一个深层机制：Agent并非“智能绕过”过期指令，而是严格遵循上下文中的文字指引，即使该指引与当前代码状态矛盾。其行为逻辑是“信任文档优先于推理”，这源于训练数据中大量高质量文档与对应代码强对齐的先验，导致模型形成“文档即事实”的默认假设。当文档失真时，Agent不会质疑来源，而是将异常归因为“需要更多探索”，从而启动冗余搜索与试错。

这一发现对工程实践提出明确建议：

• 文档应纳入CI流程：可引入轻量级校验脚本，在PR合并前自动检测指令文件中提及的路径、命令是否存在；
• 建立文档版本快照机制：与代码版本绑定，避免“最新文档”指向旧版结构；
• Agent提示词需显式声明时效性：如在系统提示中加入“本指令文件最后更新于2026-03-15，请结合当前代码树验证路径有效性”；
• 评测体系需补充过程指标：除结果正确率外，应纳入工具调用效率、路径探索深度等维度。

目前，开源社区中约23%的含指令文件仓库存在至少一处过期引用（基于356个活跃仓库抽样），而随着Agent使用场景扩展至代码审查、自动化测试、CI/CD集成等领域，文档债的影响范围将进一步扩大。它不像代码坏味道那样引发编译错误，也不像安全漏洞那样触发告警，而是以“沉默的低效”形式蚕食开发效能。

北卡州立大学的研究并未止步于问题揭示，其公开的复现包（Zenodo DOI: 10.5281/zenodo.23992004）与案例仓库（pyflow/cog/aghub）为后续工具链改进提供了实证基础。未来，文档健康度或将成为衡量项目可维护性的新指标之一——毕竟，在AI时代，写给机器看的文档，其准确性与及时性，已不再只是“锦上添花”，而是系统稳健运行的底层前提。