过期仓库指令可能把编程智能体带偏

仓库已经迁到 logging、pathlib，AI 却继续写 print()、os.path，甚至把能运行的旧模块改回去。原文讨论的就是这种冲突：代码变了，CLAUDE.md 和 AGENTS.md 没变，Agent 到底听谁的？

按文中实验，90.1% 的约定选择服从了过时指令。加入一句明确的冲突处理规则后，遵循现有代码的比例从 4.2% 升至 91.4%。这个结果值得读，但它适用的是代码约定冲突，不能直接推广成「所有文档都该让位于代码」。

Agent 看出了冲突，为什么还会照旧规则写

原文先给出两组指令文件维护数据：Denisov-Blanch 等人在 2026 年分析的 441 个公司仓库中，73.8% 的 AI 配置文件只提交过一次；Treude 和 Baltes 同年研究的 356 个公开仓库中，23.0% 的指令文件引用了已经不存在的代码元素。

接着是 Xiaonan Xu 和 Wenjing Wu 的实验，论文编号为 arXiv:2610.30571。研究使用 40 个 Python 项目，项目原有模块可用、测试通过，但指令文件与代码在 16 类约定上存在冲突，例如 print() 与 logging、os.path 与 pathlib、字符串常量与 Enum。

参与工具是 Claude Code v2.1.302，搭配 Claude Sonnet 5.5；以及 Codex CLI v0.163.0，搭配 GPT-6 Sol。

无优先级规则时，720 次约定选择中，649 次服从旧指令，占 90.1%；只有 4.2% 遵循现有代码。两种工具服从旧文件的比例分别为 86.4% 和 93.9%。

问题也不只是「没读懂仓库」。Claude Code 在 80 次运行中的 79 次，已经在最终回复指出文档与代码冲突，但相关统计中仍有 86.2% 的选择遵循旧文件。它知道模块都用了 logging 和 pathlib，新增功能时却照指令使用 print() 和 os.path。

Codex CLI 的行为更激进：80 次运行中，有 20 次重写现有模块以匹配旧 AGENTS.md，删除行数的中位数为 198 行，涉及文件数的中位数为 9 个。其中 17 次破坏了原有测试。

识别出冲突，不等于 Agent 会按维护者期待的方向解决冲突。

一句规则改变的，是冲突时听谁的

作者把原因归到上下文的交付方式。

首先，指令文件常用命令句。「Use print() for progress messages」看起来是一条必须执行的要求，即使它最初只是记录当时的代码习惯。

其次，按原文描述，Claude Code 会把 CLAUDE.md 放进带有强制服从提示的用户消息，Codex CLI 则用 INSTRUCTIONS 标签包裹 AGENTS.md。源码通常通过读文件工具进入上下文。模型为了抵御提示注入，会优先遵循指令，而不是工具返回的文本。

于是，维护者眼里的「过时说明」，到了模型那里仍然是有效命令。

研究者在用户级文件 ~/.claude/CLAUDE.md 和 ~/.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.

要看完整句子：它既要求沿用现有代码约定，也要求最终逐项报告文档冲突。后半句让维护者有机会修复信息源。

按原文报告，加入规则后，遵循代码的比例从 4.2% 升至 91.4%，即 720 次选择中的 658 次。Claude Code 从 7.5% 升至 94.4%，Codex CLI 从 0.8% 升至 88.3%。

Codex CLI 重写可用模块的运行次数从 20 次降至 0 次。总体测试通过率从 89.4% 升至 100%，其中 Codex CLI 从 78.8% 升至 100%。全部 160 次最终回复都报告了过时规则。

不过，原文对运行次数的表述不够清楚：前面称实验共 320 次运行，基线细节又分别使用两种工具各 80 次的口径；加规则后写 160 次运行，却同样统计了 720 次选择。理解大方向没有障碍，但严格比较实验分组，还需要查论文原表。

少维护一份重复规则，比反复提醒更有效

优先级规则是在冲突发生后兜底。作者另给了三种减少指令漂移的办法。

第一，把上述规则加入用户级配置，让它覆盖日常打开的仓库。原文用 cat << 'EOF' >> 分别追加到两个文件。这里的 >> 是追加，重复执行会留下重复内容。

第二，共用一份仓库规则。把构建命令和架构约定集中到 AGENTS.md，再在 CLAUDE.md 中用 @AGENTS.md 导入；Claude Code 专属要求单独保留，例如对 src/billing/ 下的修改使用 plan mode。

原文还提供另一种加载方式：在 ~/.claude/settings.json 的 pluginConfigs 中配置 cc-plugin-agents-md@builtin，把 options.instructionFiles 设为 claude-md-and-agents-md。这是文中给出的具体配置，不能脱离工具版本直接假定可用。

第三，把目录约定移出根文件。下面这段规则只针对 API 目录，避免根指令承担所有子目录的细节：

---
paths:
  - "src/api/**/*.ts"
---

## API Handler Conventions

- Validate request bodies with the schema helpers in `src/api/validators/`.
- Return structured errors through `sendApiError()`.

关键是 paths：按原文说明，这类文件放在 .claude/rules/*.md 中，匹配文件被读取或编辑时才按需加载。src/api/validators/ 和 sendApiError() 仍需跟随代码维护，拆分文件不会自动解决过时问题。

迁移或升级依赖后，作者建议运行 /doctor prompt-audit。原文称它在 Claude Code v2.1.283 及以后可用，会检查 CLAUDE.md、AGENTS.md、.claude/rules/ 和 .claude/skills/ 中的失效引用、缺失命令及冲突指令。

我的判断

我认同这篇最有价值的提醒：团队需要明确「文档与代码冲突时怎么办」，不能只要求 Agent 多读文件。实验里，Agent 已经发现冲突，继续增加阅读步骤未必能解决优先级问题。

但「沿用现有代码」有前提。对于日志、路径处理、导入方式等局部约定，它有助于避免新增功能夹带大规模改造；如果任务本来就是迁移，或者文档明确要求修复旧实现，现有代码可能正是需要改变的对象。

因此，我更倾向于把它用于日常增量开发，并为明确授权的迁移保留例外。

证据范围也要收住：实验来自 40 个 Python 项目及指定工具、模型组合，没有直接证明前端或 Node 项目能复现相同比例。共享规则、目录拆分和审计是合理的维护建议，但原文没有提供它们各自的对照数据，不能把一句规则的实验收益算到整套流程头上。

能拿来做什么

• 给日常 AI 编程补上冲突处理规则，同时要求最终回复列出文档与源码的不一致；执行明确迁移时，再说明目标约定及修改范围。
• 同时使用 Claude Code 和 Codex CLI 的仓库，可以集中维护共享构建命令与架构约定，减少两份指令各自漂移的机会。
• 前端或 Node 项目完成目录调整、校验工具迁移后，把指令文件一起纳入检查，重点核对路径、命令和辅助函数是否仍然存在。
• 审查 Agent 的改动时，留意它是否为了统一约定而修改任务范围外的可用模块，并运行原有测试验证影响。