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

眼下這個領域是按工具切割的：

• CLAUDE.md 是 Claude Code 會去找的檔案。
• GEMINI.md 是 Antigravity 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 或 Antigravity 並排跑起來，而你那些可複用的指令存在一個提示詞庫裡，不必每次會話都重新打一遍。

到了那一步，如何並行跑多個 Agent 而不亂套這篇方法論，自然就是接下來該讀的。

一句話總結

寫一個 AGENTS.md。讓它短、讓它新、讓它可移植。把每個工具都指向它，而不是每個 Agent 維護一份檔案。你的上下文不再被你碰巧最先用的那個 CLI 綁死，而你的 Agent，不管你跑的是哪幾個，都從同一頁出發。

想把所有 Agent 放在同一塊螢幕上，每個都有自己的角色，又共享你那份上下文？下載 AgentsRoom，接上你的 provider，讓你的艦隊開工。