避免 CLAUDE.md 与 AGENTS.md 配置漂移

我曾在同一个代码仓库里同时维护 CLAUDE.md 和 AGENTS.md，整整两周，这两个文件对同一件事给出了不同的说明。

我是以最糟糕的方式发现这个问题的：一个 Agent 严格执行了规则明确禁止的操作——而那条规则确实存在，只不过写在另一个文件里。

（建议的开场：确认这是否符合你的记忆，并在发布前调整成你自己的表达风格。）

Claude Code 读取 CLAUDE.md，Codex 读取 AGENTS.md。如果在同一个项目中同时使用两者，你就会有两个文件分别描述应该如何处理代码，却没有任何机制能确保它们的内容始终一致。

两个逐渐分化的文件会带来什么代价

问题不在于内容重复，而在于这种分化发生得悄无声息。

你添加了一条新规则——比如永远不要修改某个文件夹，或者提交前必须运行某条命令——然后把它写进当时正好打开的那个文件，却忘了同步更新另一个文件。

两周后，一个 AI Agent 恰好执行了这条规则禁止的操作，而错误信息并不会告诉你：“我读取的是旧版本的项目说明。”它只会报告一个完全不同的问题，于是你开始在错误的地方排查。

规则越具体，问题就越严重。通用规则往往会自然趋同，但项目特有的规则不会。

如何同时保留两个文件，又不重复维护内容

选择其中一个文件作为唯一信息源，让另一个文件指向它。只需一个三行的 AGENTS.md 就能解决问题：

`# Project instructions

The rules for this repository live in CLAUDE.md. Read that file first and follow whatever it says.`

这种方式之所以有效，是因为两个工具都能按需读取代码仓库中的文件：Agent 会打开你指定的文件，并遵循其中的内容。

这样一来，你只需要在一个地方编辑规则，“这两个文件到底应该以哪个为准”这个问题也就不存在了。

符号链接同样可行。如果你的团队全部使用 Unix，它甚至是最精简的方案：ln -s CLAUDE.md AGENTS.md，这样两个文件实际上就变成了同一个文件。

但问题在于 Windows：符号链接依赖相应权限，而且必须正确配置 Git 才能保留符号链接。如果有人在没有正确配置的 Windows 环境中克隆代码仓库，这个文件可能会变成一个只包含路径的单行文本，而 AI Agent 会把这行路径当成项目说明来读取。

文本指针不存在这种风险，代价也不过是三行文字。这正是我们更倾向采用的方案。

应该在这个文件里写些什么

真正会影响结果的不是文件格式，而是文件内容。根据我们在一个代码仓库中同时运行六个 AI Agent 的经验，以下内容最值得写进去：

• 明确说明哪些内容绝对不能修改，并附上原因。单纯写“不要编辑这个文件”很容易被忽略；如果写成“不要编辑这个文件，因为它由 X 自动生成，你的修改会在下一次构建时消失”，Agent 通常会遵守。

• 写明能够证明任务已经完成的命令。如果没有完成标准，Agent 会在自认为已经完成时直接交付。把验证命令明确写下来之后，它会主动运行命令，并在向你报告完成之前修复发现的问题。

• 如果你会同时运行多个 Agent，还要说明如何隔离各自的工作。否则，两个 Agent 可能会同时修改同一个文件，其中一个 Agent 的工作最终会丢失。

如果不同工具确实需要不同的规则怎么办

这种情况确实存在，而且这是唯一真正有理由保留两个独立文件的场景：规则针对的是工具本身，而不是项目。

你仍然应该保留指向共享规则的文本指针，只在其下方添加该工具特有的内容。绝对不能让项目规则重复存在于两个文件中。

这种方法也适用于其他 AI Agent 吗

适用，而且在情况好转之前，问题可能还会进一步恶化：每一种新工具都会带来自己专用的文件名。

采用一个源文件，再让其他文件指向它，无论未来出现多少种工具都能轻松扩展。每增加一种工具，只需添加三行文本，而不必复制整份项目手册。

如何确认两个文件都被读取了

直接询问 Agent。

在会话开始时问一句：“你加载了哪些项目说明？”一秒钟就能得到答案，比靠猜测可靠得多。

在移动文件夹之后尤其值得这样确认，因为放在子目录中的说明文件，并不一定能从工具启动时所在的任意位置被发现。

我还写了一篇完整版本，其中包含了一些这里没有篇幅展开的内容：https://canvascode.app/en/news/claude-md-vs-agents-md-in-the-same-project

如需采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。