过期的 AGENTS.md，每次 agent 开工都在收你的过路费
732 次 agent 运行，没有一次顺手把误导它的那个文件改掉。这是论文《When Instruction Files Go Stale: Documentation Debt and Hidden Cost in Coding Agents》（arXiv 2611.09802，作者 Tural Mehtiyev、Biruk Tadesse、Lawrence Arkoh、Wesley Assunção）里最安静也最扎心的一句。
实验设计很干净。AGENTS.md、CLAUDE.md 这类仓库说明文件，agent 每次开工都会先读，可它们跟所有文档一样会过期：测试目录挪了地方，文件里还写着旧路径。作者从活跃的开源项目里挑了三条真实的过期说明，一条是测试命令，一条是代码位置，一条是新增组件的流程。每条说明做三个版本：保持过期、改正、直接删掉，代码和任务都不动，让 agent 去修 22 个维护任务，最后拿两个模型的 732 条轨迹，一个工具调用一个工具调用地拆。
按摘要的结论：只要过期说明跟手上的任务相关，agent 就会照着做，有时候正确信息明明就在仓库别处。过期测试命令那一组，Claude Sonnet 5.5 每次运行平均多调用两次工具左右，比改正后的版本多出三分之一。另外两种情况，测不出差别。agent 一般都能从眼前的报错里绕出来，把任务做完就走，坏文件原样留给下一次。改正说明，指向废弃路径的操作就彻底没了；删掉说明，大部分也没了。
样本很小，三条说明里只有一条测出了效果，别过度解读。但这个形状很重要。只看任务成没成的评测，会给这些运行全部打及格，而那行过期的说明，每次开工都在多收你几次工具调用，永远收下去。说白了，这就是文档债的利息。解法很朴素也很管用：把说明文件当代码管，指定负责人，在 CI 里检查里面写的路径和命令还在不在。一个从来不修自己说明书的 agent，不会哪天突然自觉。
来源：https://arxiv.org/abs/2611.09802
← 返回所有文章
实验设计很干净。AGENTS.md、CLAUDE.md 这类仓库说明文件，agent 每次开工都会先读，可它们跟所有文档一样会过期：测试目录挪了地方，文件里还写着旧路径。作者从活跃的开源项目里挑了三条真实的过期说明，一条是测试命令，一条是代码位置，一条是新增组件的流程。每条说明做三个版本：保持过期、改正、直接删掉，代码和任务都不动，让 agent 去修 22 个维护任务，最后拿两个模型的 732 条轨迹，一个工具调用一个工具调用地拆。
按摘要的结论：只要过期说明跟手上的任务相关，agent 就会照着做，有时候正确信息明明就在仓库别处。过期测试命令那一组，Claude Sonnet 5.5 每次运行平均多调用两次工具左右，比改正后的版本多出三分之一。另外两种情况，测不出差别。agent 一般都能从眼前的报错里绕出来，把任务做完就走，坏文件原样留给下一次。改正说明，指向废弃路径的操作就彻底没了；删掉说明，大部分也没了。
样本很小，三条说明里只有一条测出了效果，别过度解读。但这个形状很重要。只看任务成没成的评测，会给这些运行全部打及格，而那行过期的说明，每次开工都在多收你几次工具调用，永远收下去。说白了，这就是文档债的利息。解法很朴素也很管用：把说明文件当代码管，指定负责人，在 CI 里检查里面写的路径和命令还在不在。一个从来不修自己说明书的 agent，不会哪天突然自觉。
来源：https://arxiv.org/abs/2611.09802
评论