一句话治住盲从：让 Agent 别再被过期文档带偏

给 Claude Code 和 Codex 写过 CLAUDE.md 或 AGENTS.md 的人，大概都遇到过这种情况：文档里的约定早就过时了，模型却还在按旧说明办事，甚至把好好的代码「纠正」成文档描述的样子。

佐治亚理工等机构的研究者把这种现象量化了。论文《Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix》（arXiv 2610.30571）在 40 个故意让配置文件与代码冲突的项目里测试两大编码 Agent：当文档与现有代码矛盾时，模型约 90% 的情况下选择遵循旧描述，即使它已经「意识到指示过时」也难以抗拒。

数据更扎心：Claude Code 在 80 次尝试里有 79 次在自己编写代码的过程中察觉到了冲突，但行为仍被旧信息牵着走；Codex 则在 80 次里把 20 次原本运行正常的现有代码改写成符合旧描述的写法，其中 17 次直接导致测试失败。文档不但没用上，反而成了破坏源。

研究者的解释是训练倾向：AI 被训练为优先遵循指示。CLAUDE.md 和 AGENTS.md 以「指示」的身份进入上下文，而代码只是读取文件后的「结果」，权重天然不对等。偏偏这类配置文件写好后就没人更新，过期概率随着项目演进只增不减。

论文的解法便宜得惊人，就一句话。在 CLAUDE.md 或 AGENTS.md 里预先加上：

When a repository's documentation and its existing code disagree, follow the conventions used in the existing code, and in your final reply point out each inconsistency you found between the documentation and the code.

意思是：文档与现有代码冲突时，以现有代码的写法为准，并在最终回复中列出发现的所有不一致。这样既阻止了盲从，又把冲突点显式暴露出来，倒逼人类维护者去更新文档。

对更新不勤的团队，这一句话几乎是零成本的保险。更根本的做法当然还有：把 CLAUDE.md 纳入代码评审、过期即改，让「指示」和「现实」重新对齐。