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

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

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

AGENTS.md 到底是什么

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

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

AGENTS.md vs CLAUDE.md vs GEMINI.md

眼下这个领域是按工具切割的：

• CLAUDE.md 是 Claude Code 会去找的文件。
• GEMINI.md 是 Gemini CLI 的约定。
• AGENTS.md 是跨工具的标准，被 Codex 和其他工具读取，设计上就是要当那个中立的文件。

三者的内容几乎一模一样：项目上下文、命令、约定。唯一真正的区别，是各个工具默认会读哪个文件名。这正是为什么手动把同一套规则复制进三个文件是一场注定要输的仗（怎么让它们保持同步，下文细说）。

如果你主要在 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.md 和 GEMINI.md 做成只有一行的文件，写上"见 AGENTS.md"，或者干脆建符号链接。一个真理来源，所有工具都喂到。
• 一个文件，按约定共享。 如果你的工具能指向自定义路径，就把它们全部对准 AGENTS.md，把其余的删掉。

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

当你同时跑好几个 Agent 时

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

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

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

一句话总结

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

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