你熬夜写的那份项目规则文件，可能正在让 AI 把你的代码改坏。
更气人的是：它自己都知道。
10 月 22 日，佐治亚理工和科罗拉多大学波德分校的两位研究者在 arXiv 挂了篇论文，标题很直白——《Stale Instruction Files Override the Code in Coding Agents: A One-Sentence Fix》，过时的指令文件压过代码，一句话修复。arXiv
他们造了 40 个 Python 小项目，每个都故意埋一个矛盾：CLAUDE.md 或 AGENTS.md 要求一种写法，仓库里已有的代码用的是另一种。比如文档写"用 print 打日志"，代码里全是 logging。然后让 Claude Code 和 Codex CLI 去加功能，带修复句和不带各跑 160 次，合计 320 次。微博arXiv
结果有点难堪。
不带修复句时，90.1% 的选择（720 个里 649 个）跟着过时文档走，只有 4.2% 跟着代码走。Claude Code 86.4% 从文档，Codex CLI 更狠，93.9%。arXiv微博
最扎心的是 Claude Code：80 次里有 79 次，它在最终回复里明确点出了冲突——原话是"现有的 concat.py、reader.py、writer.py 还在用 logging、pathlib、str.format() 和绝对导入，这与 CLAUDE.md 不符"——然后转头继续写 print。它把代码当成了不守规矩的那一方。微博
Codex CLI 几乎不吭声（80 次只提了 2 次），但干了更重的事：20 次里直接动手改老代码去迁就文档，中位数删掉 198 行、动了 9 个原有文件。改完把项目自带测试跑一遍，20 次里 17 次挂了。arXiv
为什么？论文给的解释是"指令层级"。CLAUDE.md 是作为指令塞进上下文的，Claude Code 把它放在系统提示词后面，还配一句"这些指令覆盖任何默认行为，你必须严格遵循"；而代码是 Agent 打开文件后拿到的工具输出。模型被训练成指令优先于工具输出——本意是防提示词注入，别让网页里藏的"忽略以上指令"劫持 Agent。副作用就是：文档里一行过时的话，优先级高于眼前活着的代码。微博
论文还特意排除了一个解释：这不是 Claude Code 那句吓人的前导语造成的——Codex CLI 没加任何前导语，照样 93.9% 听文档。arXiv
也不是实验室里的洁癖问题。论文引用的两项独立研究：441 个公司仓库中，73.8% 的 AI 配置文件提交一次后再没改过；356 个公开仓库中，23.0% 的指令文件引用着已经不存在的代码。真实案例更直观——Supabase 把 dashboard 升到 React 19 后，一个 skill 文件连续 13 天告诉 Agent"这是 React 18，跳过 React 19 写法"；OpenAI 自己的 Codex CLI 仓库里，AGENTS.md 有 24 天一直在要求 Agent 更新一份早就删掉的文档。arXiv
修复办法就一句话，加在用户级指令文件里（Claude Code 是 ~/.claude/CLAUDE.md，Codex CLI 是 ~/.codex/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.
翻译过来：文档和现有代码冲突时，按现有代码的写法来，并在最后回复里逐条列出你发现的不一致。它不是让 AI 无视文档，而是给"文档和代码谁说了算"补上一条明确裁决——构建命令、目录约定这些照样生效。arXiv微博
加上它，跟代码走的比例从 4.2% 跳到 91.4%，改老代码的行为归零，测试通过率从 89.4% 变成 100%。拆开看，Claude Code 从 7.5% 升到 94.4%，Codex CLI 从 0.8% 升到 88.3%，工具调用和耗时还略降。原理不复杂：这句话本身也是指令，于是冲突变成两条指令打架，而它是唯一专门管"文档 vs 代码"的那条。arXiv
但别当银弹。实验只覆盖 40 个 Python 项目、单次无人值守跑完的加功能任务，Agent 也只有 Claude Code 配 Sonnet 5.5 和 Codex CLI 配 GPT-6 Sol 这两个。其他语言、多轮长会话、有人盯着的交互模式，论文没测。16 类约定里，"金额表示"和"配置读取"两类 Claude Code 听文档的比例本来就低于一半，说明模型自身偏好也在起作用。arXiv
而且这句话只是止血——Agent 不再被带跑，那份文档依然是错的，迟早得清。至于能用 diff 或语法树判定的硬红线，社区里另有一派做法：别写进文档，写成 git pre-commit hook，在 Agent 提交那一刻用非零退出码掐断，把修复提示塞进 stderr。理由是 Agent 天生死盯最后一次终端报错，规则出现在犯错的精确时刻才最有效。知乎
两条路不冲突：一句话兜住"文档过时"这类软冲突，钩子守住"绝不能破"的硬红线。
项目、任务和分析脚本已开源在 github.com/WenJing95/stale-docs-data。那句话现在就能贴，成本大概十秒。{{{CUSTOM_HTML_TAG_15}}}
