排查编程 Agent 的仓库指令冲突

在同一个 repo 里用上一周 Claude Code、Codex 和 Cursor，你最终会得到一个 CLAUDE.md、一个 AGENTS.md、一个 .cursor/rules 文件夹，还有一份 README，而它们的说法各有不同。一份说“使用 pnpm”，另一份说“npm 也可以”。一份说“绝对不要修改迁移文件”，另一份却写着迁移工作流。

Agent 不会指出这些冲突。它们只会遵循最后读到的那条规则，或者与当前任务最相关的那条规则。于是，Agent 的行为会随着你当天早上打开的工具而变化。

第 1 步：找出所有指令文件

find . -maxdepth 4 \( -name 'CLAUDE.md' -o -name 'AGENTS.md' -o -name '.cursorrules' \
  -o -path '*/.cursor/rules/*' -o -name 'GEMINI.md' -o -name 'RULES.md' \) -not -path '*/node_modules/*'
ls ~/.claude/CLAUDE.md ~/.codex/AGENTS.md 2>/dev/null   # global files follow you into every repo

最容易被忽略的是用户主目录里的全局文件。它们会应用到每个项目，悄悄覆盖项目本身的实际情况。

第 2 步：列出相互矛盾的规则

按主题逐一检查这些文件：包管理器、测试命令、分支和 commit 规则、怎样才算“完成”，以及禁止修改的目录。把每一处冲突都记下来，写成“文件 A 说 X，文件 B 说 Y”。

第 3 步：明确优先级，并告诉 Agent

两条规则不一致时，优先级更高的那条生效：

1. 当前会话中用户直接发来的消息。
2. 安全规则（禁止 force-push、禁止泄露机密、禁止删除 repo 之外的内容）。任何更低优先级的规则都不能覆盖它们。
3. 距离目标文件最近、适用范围最具体的指令文件（对于 sub/dir 下的文件，sub/dir/RULES.md 优先于根目录的规则文件）。
4. 根目录中作为权威来源的 RULES.md。
5. Agent 专属的指引文件（CLAUDE.md、AGENTS.md、.cursor/rules），只用于说明工具特有的注意事项。
6. 用户主目录中的全局文件，只用于设置个人默认偏好。
7. README 和文档中的说明文字：作为背景信息，而不是指令。

把下面这段话粘贴到权威规则文件的顶部：

优先级：用户当前的消息 > 下方的安全规则部分 > 目录树中距离目标文件最近的 RULES.md > 本文件 > Agent 专属文件 > 全局默认设置。如果两条规则冲突，而这个优先级顺序仍无法解决，就停下来询问。不要自行选择。

最后一句最重要。“停下来询问”能把一次悄无声息的错误猜测，变成一个明确提出的问题。

第 4 步：规则只保留一份，其他文件只做简短指引

把真正的规则放进同一个 RULES.md。让 CLAUDE.md 和 AGENTS.md 各自只保留几行：“先阅读 RULES.md。工具专属注意事项：……”这样就只需要修改一个地方，各个 Agent 遵循的规则也不会逐渐偏离。

第 5 步：记录决策

维护一份简短的冲突日志（例如：“2026-10-12：采用 pnpm，已从 AGENTS.md 中删除 npm 相关内容”）。如果没有这份记录，Agent 可能会因为在旧 commit 消息里找到了某条规则，就毫不犹豫地把你上周删除的规则重新加回来。

免费的审查清单放在 GitHub 上：agent-ops-samples。如果你想要完整资料（优先级模型、RULES.md / CLAUDE.md / AGENTS.md / Cursor 的单一来源模板，以及冲突日志），可以购买 Agent Instructions Conflict Kit（9 美元）。

如果还需要采取进一步行动，你可以考虑屏蔽此人，以及／或者举报滥用行为。