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 在那個資料夾裡幹活時就會讀到它。