多 Agent 共用一套规则，Claude Code 终于开始读 AGENTS.md

同一套仓库，Codex 读 AGENTS.md，Claude Code 读 CLAUDE.md。测试命令、目录边界、提交前要跑什么，复制一份，再改一份。过两周，两个文件里已经各自长出了不同的宇宙。

好家伙，coding agent 还没开始写代码，团队先把自己写成了配置同步服务。

Anthropic 在 9 月 18 日发布的 Claude Code v2.1.277 补了一个看起来很小、其实很对症的改动。在项目没有 CLAUDE.md 时，Claude Code 会读取 AGENTS.md。官方把开关放在 /config 的 Project instructions 里，同时明确说 Bedrock、Vertex 和 Foundry 还没覆盖到。官方 release 在这里。

这不是「所有 agent 从此共享记忆」。它更像是 Claude Code 终于愿意在没有自家说明书时，去读团队已经在维护的那份说明书。

差别很大。

不少人看到 AGENTS.md 支持，第一反应是把 CLAUDE.md 删掉，仓库立刻统一。先按住。官方写的是 fallback，不是合并。仓库里仍有 CLAUDE.md 时，不能把这次更新理解成两份规则都会自动拼在一起。你以为的「统一」，很可能只是其中一份在悄悄生效，另一份安静地躺在根目录里当电子盆栽。

所以这篇不讲文件名之争，只讲一件更实在的事，怎样把「项目规则」从每个工具各写一遍，收回成团队能验收的一份事实来源。

先把规则和偏好分开

很多仓库的说明文件，什么都往里塞。

一半是项目事实，比如启动命令、测试命令、模块边界、数据库迁移步骤。另一半是某个工具的个人偏好，比如模型选择、插件、显示样式、某条只对一个 CLI 有效的快捷指令。

这两类东西混在一起，双份文件才会越维护越累。

适合放进共享 AGENTS.md 的，是任何人和任何 coding agent 都应该遵守的项目事实。比如下面这些。

# 项目工作约定

- 改动前先读 `docs/architecture.md` 与相邻模块的测试
- Web 包使用 `pnpm test`，服务端使用 `make test`
- 不修改 `migrations/` 里的已发布文件，新迁移单独创建
- 跨包改动必须说明受影响的 API 和回滚方式
- 完成前给出实际运行过的校验命令与结果

这份东西的价值不在于写得多漂亮，而在于它能被人、Codex、Claude Code 和下一个你还没装上的 agent 一起检查。它是团队交付的地基，不是给某个聊天窗口写的角色卡。

工具私有的东西就留在工具自己的设置里。这样做很朴素，但很管用。项目规则要能换工具，个人偏好没必要假装成团队宪法。

共享规则负责项目事实，不替任何工具保存私有偏好。

再具体一点，真正容易漂的往往不是「用什么模型」，而是那些看起来不起眼的交付动作。有人把前端测试写成 pnpm test，有人只跑了一个包。有人让 agent 可以顺手改依赖锁文件，另一个 agent 把它视为禁止触碰的区域。有人要求 PR 贴出失败日志，另一个只回一句完成。它们每一条都不惊天动地，叠起来就是那种最烦的线上事故，代码能跑，团队却不知道它是怎么跑过的。

共享规则文件应该优先收住这种差异。模型能力再强，也补不了一条没被写下来的迁移约束。不是哥们，靠 agent 自己猜项目习惯，最后大概率会把「看着像能用」误当成「符合团队交付标准」。

迁移前，先做一次优先级盘点

如果团队准备把共享规则放到 AGENTS.md，不要上来就批量改名。先在仓库根目录和常用子目录里找一遍 CLAUDE.md、AGENTS.md 以及各工具的规则文件，把每一份分成三类。

第一类是必须同步的项目事实，例如 build、test、lint、目录责任边界和上线前验收。

第二类是工具私有配置，例如特定模型、特定插件、终端展示习惯。这些不必强塞进共享文件。

第三类是已经过期的仪式感文字，例如「优雅地修改代码」「保持高质量」这种话。它们看着挺励志，出了 bug 时基本帮不上忙。删掉也不会有人报警，厉害了。

盘点完，再决定谁是唯一来源。对一个刚开始多 agent 协作的仓库，我更倾向于让 AGENTS.md 承担项目事实，然后保留确有必要的 CLAUDE.md 去放 Claude Code 独有规则。只是要在文件开头写清楚，谁覆盖谁，什么条件下读取。别让同事靠猜。

这里有个很土但有效的验收办法。新开一个干净会话，给 agent 一个会触发项目规则的具体任务，比如「只改服务端，运行对应测试，别碰迁移」。看它是否复述了边界，是否真的跑了正确命令，最后能不能给出验证证据。

它没遵守，就不是文案问题，是加载链路或规则表达出了问题。

把这件事写进 PR 检查项，会比在群里提醒有效得多。规则文件本身的改动也该像代码一样过审，尤其是测试命令、权限范围、生产操作和完成定义。这样下一次有人为了某个工具加一条特殊要求，团队能看见它是在补项目事实，还是只是在给自己常用的 agent 开后门。

交付不是一句完成，而是可复查的范围和验证记录。

真正该盯的是交付证据

很多团队把规则文件当作给 agent 加几句提示词。其实更值得写进去的，是完成定义。

一个 agent 说「已经修好」并不构成完成。它至少应该能回答，改了哪些文件，为什么没碰其他目录，跑了什么命令，命令结果是什么，若失败卡在哪里。这些信息不依赖某一家模型，也不依赖某一个 CLI。

这也是共享规则最适合写的部分。

当团队把「给出测试证据」「说明影响范围」「不可逆操作先停下」这些要求写成项目共同约定，换哪个 agent 都不用重新教育一遍。模型会换，IDE 会换，订阅价格也会换。验收标准没必要跟着漂。

有点子牛逼的地方正在这儿。Claude Code 读取 AGENTS.md 不会让 agent 突然更会写代码，但它让团队少维护一层无聊、又特别容易出错的翻译层。

这次更新的边界也得写在旁边

别把它当成万能兼容层。

官方 release 给了两个很清楚的限制。其一，它的触发条件是没有 CLAUDE.md。其二，Bedrock、Vertex 和 Foundry 暂不支持这项行为。云上会话、IDE 插件和本地 CLI 的版本也可能不齐，团队如果同时跑多种入口，不能只在一台机器上看见生效就宣布迁移完成。

还有一点常被忽略，规则文件解决的是「该怎么干活」，不是「知道发生过什么」。它能告诉 agent 用什么命令、不要碰什么目录，却不会自动补齐另一个 agent 已经试过哪些方案、为什么某次测试失败、哪个决定已经被推翻。共享规则和任务记录是两回事，别把一份 Markdown 当成万能内存条。

所以比较稳的做法，是把 AGENTS.md 维护得短、具体、可验证。项目事实放进去，执行历史放在 issue、PR、任务记录或提交说明里。两样都要有，别让 agent 在规则里考古。

这波更新真正值得高兴的，不是多了一个文件名，而是 agent 生态终于往「项目规则属于项目」靠近了一小步。

你们仓库现在是共用一份规则，还是每个 coding agent 各养一份？哪一类内容最容易先漂掉？