AGENTS.md：一个上下文文件喂饱所有编码 Agent（Codex、Antigravity、Claude）

你花了一个下午写好一份干净的 CLAUDE.md。你的 Agent 终于不再瞎猜你的技术栈，开始跑正确的测试命令了。结果同事用 Codex 打开同一个仓库，你又在一个分支上试了试 Antigravity CLI，这套来之不易的上下文一点都没带过去。每个工具都想要自己的文件，放在自己规定的地方。

AGENTS.md 就是解决这团乱麻的答案：一个纯 Markdown 文件，放在仓库根目录，任何编码 Agent 在动你代码之前都会先读它。

AGENTS.md 到底是什么

没有魔法。它就是一个名为 AGENTS.md 的 Markdown 文件，通常放在仓库根目录，Agent 在开始干活之前把它当作常驻指令加载进来。你可以把它看作你写给 AI 队友、而不是写给人类队友的那份 README：这个项目是什么、怎么构建和测试、要遵守哪些约定、要避开哪些坑。

它是一个开放约定，已经被 Codex 和越来越多的 Agent 工具读取，目标很明确：在它们之间可以通用。一个文件，喂饱多个 Agent，而不是每个工具配一份量身定制的文件。

AGENTS.md vs CLAUDE.md vs GEMINI.md

这篇指南最初写成时，每个工具都只找自己的文件。此后，大多数工具已经统一到了 AGENTS.md：

• Codex 读 AGENTS.md，GitHub Copilot CLI、Cursor、Amp 以及大多数较新的 Agent CLI 也一样。
• Claude Code 读 CLAUDE.md，而从 2.1.277 版本起，当你的工作目录及其上级目录里既没有 CLAUDE.md 也没有 CLAUDE.local.md 时，它也会自己读 AGENTS.md。如果存在 CLAUDE.md，Claude 就只读这个文件，除非你在 /config 里改了 Project instructions 这个设置。
• Antigravity CLI 读仓库根目录或任意子目录下的 AGENTS.md 或 GEMINI.md，外加一个 .agents/rules/ 文件夹，以及 ~/.gemini/ 下的全局规则。

三者的内容几乎一模一样：项目上下文、命令、约定。仍然不同的，是同时存在多个文件时，工具会选哪一个。这正是为什么手动把同一套规则复制进三个文件是一场注定要输的仗（怎么让它们保持同步，下文细说）。这些行为我们在 2026 年 10 月 10 日对照 Claude Code 的记忆文档和 Antigravity 的规则文档核实过。

如果你主要在 Claude Code 里干活，我们的 CLAUDE.md 指南深入讲了 Claude 专属的结构。AGENTS.md 就是这份文件那个不绑定 provider 的中立兄弟。

该往里写什么

写短，写得信息密度高。Agent 每个任务都会读它，所以每一行都在抢注意力。核心几条：

• 技术栈，一句话讲完。 "Next.js 16、TypeScript、Prisma、MariaDB。" 不要历史沿革，不要营销话术。
• 真正要紧的命令。 怎么安装、运行、构建、测试和 lint。给确切的命令：npm test，而不是"跑一下测试"。
• 约定。 命名、文件布局、错误处理，这些是你在 review 时真的会卡人的模式。
• 一张目录地图。 用两行说清东西都放在哪，省得 Agent 瞎 grep。
• "动手前先读"的规则。 "改 billing/ 下任何东西之前，先读 docs/payments.md。" 单单这一个习惯就能避免大量损失。
• 铁打的禁令。 "没人让你建分支就别建。""提交的文件里不要出现绑定本机的绝对路径。"

哪些错误会让 Agent 直接无视这个文件

上下文文件出问题是无声的。Agent 不会报错，它只是悄悄跑偏。常见原因：

1. 太长。 一个 600 行的文件会把真正要紧的那五条规则埋掉。凡是 Agent 自己读代码就能推断出来的，统统删掉。
2. 自相矛盾。 一节里写"永远要写测试"，另一节写"原型阶段跳过测试"。Agent 会随机挑一条照办。
3. 绑定本机的路径。 提交的文件里出现 /Users/you/project/...，会对你每个同事、对其他任何机器上的每个 Agent 都失效。路径要写成相对的。
4. 过期的命令。 测试命令半年前就改了，文件没改。现在 Agent 满怀信心地跑着错的东西。
5. 没有优先级。 什么都"重要"，于是什么都不重要。把不可妥协的放最前面，并打上标签。
6. 倾倒文档。 这是指令，不是 wiki。链接到你的文档，别把它整段粘进来。

在多个 provider 之间保持同一份上下文

这才是大多数指南略过的实操部分。如果你或你的团队跑着不止一个 Agent CLI，你肯定不想要同一套规则的三份各自漂移的副本。

两条干净的路子：

• 只要一个 AGENTS.md，别的都不要。 如果没人需要只针对 Claude 的规则，就只留一个 AGENTS.md：Codex、Antigravity CLI 和 Claude Code 2.1.277 及以上版本都会读它。坑是无声的：之后加进来一个 CLAUDE.md，或者一个个人用的 CLAUDE.local.md，Claude Code 就不再读 AGENTS.md 了。
• 一个权威文件，一个导入。 把所有内容都放进 AGENTS.md，让 CLAUDE.md 以 @AGENTS.md 这一行开头，再在下面写只针对 Claude 的规则。Claude 会先读被导入的文件。我们自己的仓库就是这么做的：它的 CLAUDE.md 就只有这一行。符号链接（ln -s AGENTS.md CLAUDE.md）也行，但在 Windows 上不太好用：在 Windows 上创建符号链接需要管理员权限或开发人员模式，而且没开 core.symlinks 的克隆拿到的是一个只有一行的文本文件，而不是你的指令。

不管哪条路，规则都一样：上下文只写一次，而不是每个 provider 写一次。这也是它能保持正确的唯一办法，因为单一文件才是大家真正会去维护的那个文件。

当你同时跑好几个 Agent 时

仓库级的 AGENTS.md 回答的是"这是个什么项目"，它回答不了"这个 Agent 是谁"。当你在同一份代码上并行跑一个后端 Agent、一个前端 Agent 和一个 QA Agent 时，每个都既需要那份共享的项目上下文，又需要自己的角色。

这正是 AgentsRoom 在你的 AGENTS.md 之上加的那一层。每个 Agent 拿到一个专属角色和自己的 system prompt（DevOps、前端、安全等等），让共享文件保持精简的同时，每个 Agent 又都清楚自己的本职。它在设计上就是与 provider 无关的，所以同一套配置可以让 Claude、Codex 或 Antigravity 并排跑起来，而你那些可复用的指令存在一个提示词库里，不必每次会话都重新打一遍。

到了那一步，如何并行跑多个 Agent 而不乱套这篇方法论，自然就是接下来该读的。

一句话总结

写一个 AGENTS.md。让它短、让它新、让它可移植。把每个工具都指向它，而不是每个 Agent 维护一份文件。你的上下文不再被你碰巧最先用的那个 CLI 绑死，而你的 Agent，不管你跑的是哪几个，都从同一页出发。

想把所有 Agent 放在同一块屏幕上，每个都有自己的角色，又共享你那份上下文？下载 AgentsRoom，接上你的 provider，让你的机群开工。

常见问题

AGENTS.md 是什么？

一个 Markdown 文件，通常放在仓库根目录，编码 Agent 在开始干活之前把它当作常驻指令加载：这个项目是什么、怎么构建和测试、要遵守哪些约定、要避开哪些坑。它是跨工具共享的开放约定，而不是某一个工具的专属文件，Codex、Antigravity CLI、GitHub Copilot CLI、Cursor、Amp 都会读取它，Claude Code 从 2.1.277 版本起也会读取。

Claude Code 会读 AGENTS.md 吗？

会，从 Claude Code 2.1.277 起，但前提是你的工作目录及其上级目录里没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。这时它会从工作目录往上加载每一个 AGENTS.md，并在打开某个子目录里的文件时加载该子目录的 AGENTS.md。如果存在 CLAUDE.md，Claude 就只读这个文件，除非你在 /config 里把 Project instructions 设为 claude-md-and-agents-md。在更早的版本上，在 CLAUDE.md 开头写一行 @AGENTS.md。

Antigravity 用的是 AGENTS.md 还是 GEMINI.md？

两个都用。Antigravity 会读取仓库根目录或任意子目录下的 AGENTS.md、GEMINI.md 或 .agents/rules/ 文件夹，以及 ~/.gemini/ 里的全局规则。这些规则是叠加的，不会互相替换；两条规则冲突时，以更具体的那个目录的规则为准。

该保留 AGENTS.md 还是 CLAUDE.md？

保留 AGENTS.md，作为你唯一维护的那个文件。如果你还需要只给 Claude 的规则，就加一个第一行是 @AGENTS.md 的 CLAUDE.md，把这些规则写在下面：Claude 会先读被导入的文件。如果不需要，对 Claude Code 2.1.277 及以上版本来说，只有 AGENTS.md 就够了。别留两份完整的相同规则：没人改的那份会过时。

AGENTS.md 应该放在哪里？

适用于所有地方的规则，放在仓库根目录。Claude Code 和 Antigravity 也会读取子目录里的 AGENTS.md 文件，所以一个有自己命令的包或服务可以带上自己的文件，Agent 在那个文件夹里干活时就会读到它。