AGENTS.md 是什麼？寫法範本、六種工具支援與 CLAUDE.md 比較

AGENTS.md 是寫給 coding agent 的專案說明檔，用 Markdown 記錄建置與測試指令、程式碼慣例和操作禁區。把它放在儲存庫根目錄，支援的工具便可依各自的載入規則使用；Claude Code 有條件直接讀取，Gemini CLI 則需要設定檔名。它沒有必填欄位，也不能取代權限設定與 CI。

影片：5 分鐘理解 AGENTS.md

先用影片掌握專案規則的寫法、Codex 載入順序，以及 Claude Code 與 Gemini CLI 的支援差異。在 YouTube 觀看完整解析。

影片素材授權與改作紀錄

以下四項素材已剪輯、裁切，原聲未採用；適用片段另作超分與色彩修正。

1. Computer work at home
   作者：Sounds of Changes / Erik Pålsson；錄音：Helena Törnqvist。
   原始素材與作者紀錄 · CC BY 3.0
2. Speed typing with dvorak
   作者：Enteryourname0000。
   原始素材與作者紀錄 · CC0
3. Coding da Vinci 2014
   攝影與剪輯：Zum Grauen Bären — Christian Fussenegger、Yvonne App；設計：FUK Graphic Design。原片音樂：Josh Woodward（本集未採用）。
   原始素材與作者紀錄 · CC BY 4.0
4. Debugging JavaScript – Chrome DevTools 101
   作者：Google Chrome Developers。
   原始素材與作者紀錄 · CC BY 3.0

官方影片片段的來源另見片內標示；此區未將其列為 CC 授權素材。

同一個儲存庫，白天用 Codex 在雲端跑背景任務，下班前用 Claude Code 收尾，同事偏好 Cursor，demo 當天開 opencode。每個工具都很聰明，但沒有一個天生知道你們的測試要下哪個指令、哪個資料夾絕對不能動、commit 訊息有沒有固定格式。這些事在對話裡重講一遍不難，講到第十次就會開始想：有沒有一個地方寫一次，所有工具自己去看？AGENTS.md 就是為這個需求長出來的檔案。

它是一份放在儲存庫裡的 Markdown 檔，內容寫給 coding agent 讀：專案怎麼建置、怎麼測試、程式碼有什麼慣例、地雷在哪。它不綁任何一家廠商，OpenAI 的 Codex、Google 的 Gemini CLI、JetBrains 的 Junie、GitHub 的 Copilot cloud agent 都認得它，Cursor 與 opencode 也讀。下方整理檔案位置、六種工具的支援差異、可直接修改的範本，以及規則沒有生效時的排查方式。工具載入行為依 2026 年 10 月 6 日的官方文件整理。

AGENTS.md 是放在儲存庫裡的純 Markdown 說明檔，定位是「給 agent 的 README」。沒有必填欄位、沒有 schema，寫你想讓 agent 知道的事就夠。規格由 OpenAI、Google、Cursor 等團隊協作發起，現在交由 Linux Foundation 之下的 Agentic AI Foundation 治理。

常見做法是以根目錄保存通用規則，子目錄補充局部指示；實際搜尋路徑、合併順序與重讀時機由工具決定。對話中的明確要求可以覆寫專案文件指示，仍受工具權限與更高優先序規則限制。

支援程度是一條光譜：Codex、opencode、Cursor、Copilot cloud agent 原生就讀；Claude Code 從 2.1.277 版起，在專案裡沒有 CLAUDE.md 時會直接讀，也能設成兩者都讀；Gemini CLI 預設讀 GEMINI.md，要用設定把 AGENTS.md 加進檔名清單。

它是建議，不是強制。必須阻擋的操作應交給適用的 hooks、權限規則與 CI；AGENTS.md 負責讓 agent「知道」，不負責讓 agent「服從」。

AGENTS.md 是什麼：把「給 agent 的 README」變成跨工具標準

AGENTS.md 官方網站給它的定義很直白：一個簡單、開放的格式，用來引導 coding agent。講白了就是「agent 版的 README」，一個固定、可預期的位置，存放專案 context 與指示，讓 AI coding agent 在你的專案上工作得更順。人類看 README.md 認識專案，agent 讀 AGENTS.md 取得同一份認知，這個類比就是整個標準的核心。

格式上它寬鬆到幾乎不設限：就是標準 Markdown。官方 FAQ 明講，AGENTS.md 只是普通的 Markdown，標題隨你用，agent 解析的就是你寫出來的文字本身。你可以用 H2 分節、用條列、貼指令，也可以只寫十行。標準規範的是「檔名叫什麼、放在哪裡、怎麼被找到」，不管內容長什麼樣，這也是它能同時被二十幾個工具接受的前提：門檻夠低，誰都進得來。

這個格式不是 OpenAI 單方面拍板。官方說法是它由 AI 軟體開發生態系的協作長出來，最早的參與者包括 OpenAI Codex、Amp、Google 的 Jules、Cursor 與 Factory，現在規格交由 Linux Foundation 之下的 Agentic AI Foundation 管理。規格本體放在GitHub 上以 MIT 授權公開的儲存庫，官網宣稱有超過六萬個開源專案採用，這是網站公布的採用數量。採用清單上有 20 多個名字，除了前面提過的，還包括 VS Code、Windsurf、Devin、Zed、Warp、Aider、goose、RooCode、Kilo Code、Junie、Semgrep 與 Augment Code，橫跨終端工具、編輯器、雲端代理與資安掃描。哪個工具今天還在清單上，以官網當下內容為準，這個生態仍在變動。

一個常見的混淆先拆掉：AGENTS.md 跟 llms.txt 名字裡都有 AI 味，層級卻完全不同。AGENTS.md 在你的儲存庫裡，讀者是「你授權進來工作的 agent」，性質是工作指示；llms.txt 通常放在網站根目錄，提案目的是給使用網站資訊的模型一份站內內容選單，性質接近對外宣告，而且它的實際效果在實務上仍有爭議，站上對llms.txt 實際效果的檢驗另有完整拆解。把兩者分開，才不會把專案規則寫進網站行銷檔，也不會誤以為放了一個 txt 檔，agent 就會自動懂你的程式碼。

檔名少一個 s：agent.md 是同一件事嗎

標準檔名是複數的 AGENTS.md，全部大寫。只放 agent.md 的專案，對多數工具來說等於沒放，工具找的就是那個精確檔名。有些早期採用者用的是單數的 AGENT.md，官方 FAQ 對這些專案給了兩行搬家指令：先把檔案改名成複數，再建一個反向的符號連結，讓寫死舊檔名的腳本與文件不會斷。

mv AGENT.md AGENTS.md
ln -s AGENTS.md AGENT.md

多數 agent 讀到連結時，讀到的就是同一份內容，等於一分維護、兩個檔名都通。新專案不需要這層相容，直接從 AGENTS.md 開始；你在搜尋或文件裡看到有人寫 agent.md 怎麼寫，談的通常也是同一套標準，只是檔名少了一個 s。

agent 怎麼讀 AGENTS.md：根目錄、巢狀與優先順序

基本盤很簡單：先在儲存庫根目錄放一份，再確認使用工具的載入條件；部分工具預設讀取，部分需要設定。讀取時機多半是「動工之前」，例如 Codex 官方文件明講，它會在做任何工作之前先讀 AGENTS.md，而且每個 run 只讀一次，在 TUI 裡大約等於每個 session 一次。這代表你中途改檔案，同一個 session 不一定會重讀，改完規則後重開 session 或重跑指令，是最保險的驗證方式。

各工具的讀取時點其實有譜系，跨工具工作時值得記住：Codex 是每個 run 重建一次指示鏈，等於每次啟動都重讀；Claude Code 在符合檔案選擇設定時，於 session 開始載入沿途的 AGENTS.md，子目錄的檔案則在讀到該目錄檔案時按需載入；Gemini CLI 更積極，把串接好的內容隨每個 prompt 送出，改完檔案可以用 /memory refresh 重掃。同一份規則改下去，三個工具的生效時間點不同，排查「為什麼新規則沒生效」時，先確認該工具的重讀時機，而不是懷疑檔案內容。

monorepo 與多套件專案靠巢狀支援：官方的建議是每個 package 再放一份自己的 AGENTS.md，官網的一般約定是較近的局部指示優先；是否自動發現、何時載入與如何處理衝突，仍依工具實作而定。規模可以長到什麼程度？官網以 OpenAI 自己的主要儲存庫為例，說裡面有 88 份 AGENTS.md：根目錄那份寫全域慣例，各服務目錄那份寫自己的測試指令與禁區，由各工具依自己的搜尋與載入機制取得適用規則。這不是炫技，是把「全域規範」與「在地規範」分層管理的自然結果。

AGENTS.md 官網建議衝突時以離正在編輯的檔案最近的指示為準，使用者在對話裡的明確要求優先於專案文件。不同工具的實際搜尋範圍仍要分開確認：例如 Codex 啟動時建立的是從專案根目錄到當前工作目錄的指示鏈。反過來利用它：看到 agent 行為跟檔案不一致時，先想想這個 session 裡是不是有人（包括你自己）下過更具體的指示。

還有一個實用的用途：讓工具知道該執行哪些驗收指令。官網說明，如果你在檔案裡列了測試指令，agent 會在結束任務前嘗試執行相關的程式化檢查，並修復失敗再收工。這讓 AGENTS.md 不只是風格建議，而是把驗收標準寫進去的地方：建置、測試、lint 指令寫得越明確，agent 自我檢查的閉環就越完整。想更系統化地設計「讓 agent 自己跑、自己驗、知道何時停」的流程，可以往迴圈工程的方向延伸，兩者是同一個問題的兩個層次。

心態上把它當活文件。官方鼓勵 AGENTS.md 像其他文件一樣隨時更新，不必一次寫到完美。實務上比較健康的節奏是事故驅動：agent 每踩一次坑、每次 code review 抓到一個「它本來該知道」的問題，就回去補一條規則。檔案隨專案一起演化，價值才會累積。

各工具怎麼支援：Codex、Claude Code、Gemini CLI、opencode、Cursor、Copilot 的實際行為

標準要成立，得看工具怎麼實作。「支援 AGENTS.md」五個字背後至少有三種程度：原生預設就讀、有條件讀、要設定才讀。跨工具團隊至少要弄清楚自己用的那幾個落在哪一格，單一檔案策略才知道能不能成立。先看總表，再逐個工具展開。

工具	預設行為	讀取位置與階層	與其他記憶檔的關係
OpenAI Codex	預設就讀	全域 ~/.codex/AGENTS.md，加上專案根到當前目錄逐層收錄	同目錄有 AGENTS.override.md 時優先；config.toml 可加替代檔名與 32 KiB 上限
Claude Code	沒有 CLAUDE.md 時直接讀	工作目錄與上層的 AGENTS.md 與 .claude/AGENTS.md，子目錄按需載入	預設有 CLAUDE.md 就只讀 CLAUDE.md；可設成兩者都讀；AGENTS.local.md 不讀
Gemini CLI	預設讀 GEMINI.md，需設定才讀 AGENTS.md	全域 ~/.gemini/、工作區與父目錄；工具存取檔案時沿目錄往 trusted root 載入 JIT context	context.fileName 接受清單，可讓 GEMINI.md 與 AGENTS.md 並存
opencode	預設就讀，主要規則檔	V1：全域與往上找規則檔；V2：先載入全域與工作區上層檔案，存取子目錄時再按需載入	V1 有 CLAUDE.md fallback；V2 只識別 AGENTS.md
Cursor	預設就讀	專案根與子目錄，巢狀與父層合併	定位為 .cursor/rules 的純 Markdown 替代，無 frontmatter
Copilot cloud agent	預設就讀	**/AGENTS.md，任意目錄	同時支援 copilot-instructions.md、CLAUDE.md、GEMINI.md 等五種檔案

OpenAI Codex：把 AGENTS.md 當主要記憶機制的原始推手

Codex 對 AGENTS.md 的搜尋與合併有明確定義，也是標準最早的推手之一。根據Codex 官方文件的 AGENTS.md 頁，它讀兩層：全域層是 ~/.codex/AGENTS.md，也可放 AGENTS.override.md 蓋掉前者，內容放你跨專案的個人工作約定；專案層從儲存庫根目錄一路走到當前目錄，每個目錄至多取一份，同目錄的優先序是 AGENTS.override.md、AGENTS.md，再來才是你在 config.toml 用 project_doc_fallback_filenames 自訂的替代檔名。若找不到專案根，就只檢查當前目錄。

合併行為有明確規則：找到的檔案由根目錄往下串接，越靠近當前目錄的排在越後面，因此在合併後的提示裡覆寫先前的指引；空檔案直接略過，合併總量超過 project_doc_max_bytes 就停止收錄，預設值是 32 KiB。32 KiB 聽起來很大，但巢狀多層的 monorepo 是真的會撞到，官方提供兩種調整方式：提高 project_doc_max_bytes，或將局部規則拆進適用的子目錄檔案；每次載入的規則仍應保持精簡。

官方文件給的巢狀範例可以直接借用：根目錄的 AGENTS.md 規定「送 PR 前跑 npm run lint，公開工具函式要寫進 docs/」，而 services/payments/ 目錄放一份 AGENTS.override.md，內容改為「這個服務用 make test-payments 測試，不要在未通知資安頻道前輪替 API key」。Codex 走到該目錄工作時，override 生效、同目錄的 AGENTS.md 被忽略，其他目錄完全不受影響。code review 的規則也可以這樣分層：整個 repo 的檢查放根目錄，特定服務的檢查放進該服務的目錄，官方的說法是把規則放在離它管理的程式碼最近的地方。

想確認規則真的被吃到，官方建議直接問它：跑一次 Codex 並下「總結目前的指示」這類 prompt，看它複述的內容對不對；更硬的稽核是在啟動時指定 log 目錄，再翻 session 紀錄找實際載入的檔案清單。行為異常時的排查順序也是官方給的：先看是不是上層目錄殘留 AGENTS.override.md，再確認 CODEX_HOME 有沒有被指去別的地方。Codex 本身的安裝、方案與操作，OpenAI Codex 的完整介紹另有專文，此處不重複。

Claude Code：有 CLAUDE.md 時的條件式讀取

Claude Code 從 2.1.277 版起原生支援讀 AGENTS.md。官方記憶文件給的預設規則很明確：工作目錄與其上層目錄都沒有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 時，Claude 直接讀 AGENTS.md；一旦其中任何一份存在，預設就只讀 CLAUDE.md。注意這個檢查不含你家目錄的 ~/.claude/CLAUDE.md 與組織管理層檔案，那兩者照常載入，與 AGENTS.md 並存不衝突。

這個預設藏著一個實務陷阱：專案用 AGENTS.md 當單一真相，某天你為了放個人偏好而加了 CLAUDE.local.md，Claude 就默默不讀 AGENTS.md 了。官方文件特別點名這件事，解法是在 session 裡執行 /config，把 Project instructions 設成 claude-md-and-agents-md，兩者都讀；同一個設定也有 claude-md（只讀 CLAUDE.md）與 managed-only（只讀組織管理層）等值，還能寫進 settings.json 的 pluginConfigs 區塊，從下一則訊息起生效，之後的新 session 也會沿用；手動寫檔可放在 ~/.claude/settings.json，也支援 –settings 指定檔案或 managed settings。2.1.285 起使用 cc-plugin-agents-md@builtin，較早版本的 plugin ID 為 agents-md@builtin，專案層或 local settings 不會套用這個選項。

載入範圍的細節：session 開始時，Claude 會載入工作目錄與上層的每份 AGENTS.md 與 .claude/AGENTS.md，互動模式會顯示一行「AGENTS.md loaded」訊息讓你確認；子目錄的 AGENTS.md 則是在 Claude 讀到該目錄的檔案時按需載入，前提是那個子目錄沒有自己的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。檔案內的 @path 匯入語法照常展開；AGENTS.local.md、AGENTS.override.md 與 .agents/ 目錄下的東西則明確不讀。v2.1.280 起可在 session 裡跑 /memory 或 /context，確認載入清單；v2.1.277 至 v2.1.279 不會列出直接讀取的 AGENTS.md，應改問 Claude 目前的專案指示。

還有三個細微差異，重度使用者會踩到：經由這套設定載入的 AGENTS.md，不會觸發 InstructionsLoaded hooks，靠 hooks 做注入的既有流程要改走 CLAUDE.md 匯入；用 –add-dir 額外掛進來的目錄，需設定 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 才會載入其中的 CLAUDE.md；其中的 AGENTS.md 不會透過這條路徑載入；AGENTS.md 裡 @ 匯入工作目錄以外的檔案時，不會跳核准提示，只在這個專案早就核准過外部匯入時才載入。版本方面也要留意：從 2.1.276 或更早升級後的第一個 session 可能還讀不到，下一個 session 才生效，官方對這些邊界都有明說。

若你的專案兩種檔案都需要，官方給的並存配方很乾淨：建一份 CLAUDE.md，內容只有 @AGENTS.md 這行匯入，Claude 專屬指示寫在匯入下方。symlink 也行，ln -s AGENTS.md CLAUDE.md 一行搞定，但有兩個但書：透過連結寫入會被工具拒絕，得回頭改本體；Windows 上建符號連結需要管理員權限或 Developer Mode；Git 在 core.symlinks 未啟用時，會把連結 checkout 成純文字檔，跨平台團隊官方建議用匯入、不要用連結。CLAUDE.md 本身的四層記憶結構與寫法紀律，CLAUDE.md 的記憶檔與載入規則談得更細；工具本身的安裝與操作見Claude Code 完整教學。

開發者 Simon Willison 在 2025 年分享過 CLAUDE.md 匯入 AGENTS.md 的做法；目前 Claude Code 已另有條件式原生支援，這則貼文可作為匯入方式的歷史例子。

Gemini CLI：預設檔名不同，一行設定解決

Gemini CLI 的記憶檔預設叫 GEMINI.md，不會自動去讀 AGENTS.md，這是搜尋「AGENTS.md vs GEMINI.md」的人最常撞到的牆。根據Gemini CLI 官方說明文件，它的階層制很完整：全域的 ~/.gemini/GEMINI.md 套用所有專案，載入工作區與父目錄的 context；工具存取檔案或目錄時，再沿該目錄與祖先目錄到 trusted root 找 JIT context。已載入的內容會串接後隨每個 prompt 一起送出。

要讓它吃 AGENTS.md，官方做法是在 settings.json 的 context.fileName 指定檔名，而且這個欄位接受清單，例如同時列 AGENTS.md、CONTEXT.md、GEMINI.md，三者並讀。這對多工具專案是關鍵設計：你不必在兩個檔名之間二選一，讓 GEMINI.md 保留給 Gemini 專屬調校、AGENTS.md 當跨工具主檔，一行設定就並存。驗證用 /memory 指令，show 顯示目前載入的完整內容，refresh 重新載入，list 列出載入路徑。

例如在專案的 .gemini/settings.json 設定以下檔名清單，便能同時保留通用規則與 Gemini 專屬內容：

{
  "context": {
    "fileName": [
      "AGENTS.md",
      "GEMINI.md"
    ]
  }
}

opencode：把 AGENTS.md 當第一公民的開源工具

opencode 以 AGENTS.md 為主要規則檔，但 V1 與 V2 的搜尋方式不同。下列 CLAUDE.md 相容行為出自 V1 文件。依opencode 的規則文件，它啟動時從當前目錄往上找規則檔，同時認得 AGENTS.md 與 CLAUDE.md，同層兩者並存時 AGENTS.md 勝出，每類第一個命中的檔案才算數。全域層的 ~/.config/opencode/AGENTS.md 套用到所有 session，官方建議放個人規則、不進版控；它甚至會 fallback 去讀 ~/.claude/CLAUDE.md，讓 Claude Code 的使用者近乎無痛搬家，不想被讀也有環境變數可以整組關掉。

V1 的 opencode.json 可透過 instructions 指定額外文件，接受本地路徑、glob 與遠端 URL，例如 packages/*/AGENTS.md。V1 文件也說明不會自動解析指示檔內的文件參照，需要用設定加入，或教 agent 按需讀取。執行 /init 可以掃描專案生成或改善現有檔案，官方明確說既有檔案會被就地改善、不會整份覆蓋。

另需核對 opencode V2 的 instructions 文件：V2 在 read 或 list 存取工作區下的路徑時，會自動載入沿途的 AGENTS.md；巢狀檔案按由近到遠的順序載入並去重，但 OpenCode 不會自動解決規則衝突；V2 只識別 AGENTS.md，沒有 V1 的 CLAUDE.md fallback。目前 V2 雖接受 instructions 陣列，文件仍註明尚未實際載入其中的檔案、glob 與 URL，因此不能把 V1 的設定直接當成 V2 的生效方式。

Cursor：想要純文字規則就用它，.cursor/rules 之外的簡單選項

Cursor 官方規則文件對 AGENTS.md 的定位一句話講完：純 Markdown 的 agent 指示，是 .cursor/rules 的簡單替代品，支援放在專案根目錄與子目錄。沒有 frontmatter、沒有 globs、沒有套用條件，文件甚至明講，如果你偏好純 Markdown，就改用 AGENTS.md。巢狀檔案與父層合併，越具體的指示越優先，行為與標準精神一致。

取捨在於控制粒度：.cursor/rules 有路徑比對、條件套用這類精細機制，AGENTS.md 沒有；但 AGENTS.md 讓通用規則可以沿用到其他支援的工具；換工具時仍要確認檔名設定與載入條件。實務上不少團隊兩層並用：通用規範放 AGENTS.md 給所有工具讀，Cursor 特有的路徑規則留在 .cursor/rules，各取所長。要注意的是，純 .md 檔直接丟進 .cursor/rules 是不會生效的，規則系統需要 frontmatter，這是文件明說的行為。

GitHub Copilot cloud agent：一份清單讀五種指示檔

GitHub 的 cloud agent，也就是先前的 coding agent，走大包容路線。依官方最佳實踐文件，它讀的指示檔清單包括 .github/copilot-instructions.md、.github/instructions/ 底下可依路徑套用的 .instructions.md 檔案、**/AGENTS.md、/CLAUDE.md 與 /GEMINI.md，等於把幾家主流工具的慣例檔全部收進來。優先序上，文件明說 repository 層的指示優先於 organization 層。

用 copilot-instructions.md 的人有一件事要記得：它的影響範圍不只是 agent。官方明說這份檔案同時套用到 Copilot Chat 與 code review，寫得太針對 agent 的指示，會連你在編輯器裡的聊天與 PR 審查一起影響。AGENTS.md 任意目錄都讀的特性，加上它是跨工具標準，讓它很適合當主檔；copilot-instructions.md 保留給「只想影響 GitHub 生態」的那類規則。第一次指派任務時，Copilot 也會在 PR 留言給出自動生成指示的連結，可以當草稿起點，再人工整理進 AGENTS.md。

放同一份檔案，六種讀法的實際後果

把六個工具的行為放在一起看，幾個後果會浮出來。第一，Gemini CLI 沒設定前完全不讀 AGENTS.md，這是最常見的「我放了卻沒生效」：以為全團隊規則已上線，其實只有部分工具吃到。第二，Claude Code 的條件式讀取讓 CLAUDE.local.md 這類個人檔案有靜默停讀的副作用，多人協作時很難互相發現。第三，巢狀不是人人自動：Codex 逐目錄收錄，Cursor 子目錄支援，opencode 還要區分 V1 的 instructions 設定與 V2 的按需載入，同一份 monorepo 佈局在不同工具和版本上的實際覆蓋範圍不同。

可以先請團隊用每個工具各跑一次「總結你目前遵循的專案規則」，把輸出攤開做初步對照。再查工具提供的載入路徑或記憶清單，並到需要局部規則的目錄執行一項可驗證任務。模型的摘要不能單獨證明所有檔案都已載入；上線新的說明檔策略前與每次大改後，都應重新確認。

AGENTS.md 怎麼寫：建議章節、可直接複製的範本與被遵守的原則

官方建議的章節，與一個好用的判斷標準

官網給了一份建議章節清單：專案概述、建置與測試指令、程式碼風格、測試說明、資安考量，再往外延伸到 commit 與 PR 慣例、部署步驟、大型資料集位置這類「你會告訴新隊友的事」。這份清單是起筆的好架構，但它只是建議，真實專案多半會長出自己的分節方式，標準本來就不強制任何結構。

比章節清單更實用的是判斷標準：把這份檔案當 onboarding 文件寫。想像你錄取了一位很強、但完全沒看過這個專案的工程師，入職第一小時你會口頭交代什麼？那些內容就是 AGENTS.md 該放的。反過來說，他不會問的（框架的基本語法）、翻程式碼就知道的（函式長相）、經常變動的（這週衝刺目標），都不必寫進去。這個標準能擋掉大半不知道該不該寫的猶豫。

可直接複製的 AGENTS.md 範本

下面這份範本以一個用 TypeScript 與 pnpm 的網站專案為例，把官方建議的章節填成具體內容。複製到儲存庫根目錄後，把指令與路徑換成你專案的實際值，很快就有一份能上線的版本。

# AGENTS.md

## 專案概述
- 本專案是電商後台，TypeScript + React，套件管理用 pnpm
- 應用程式原始碼在 src/，共享套件在 packages/

## 環境與常用指令
- 安裝相依套件：pnpm install
- 本機啟動：pnpm dev
- 建置：pnpm build
- 只針對單一套件操作：pnpm --filter <package-name> build

## 測試
- 跑全部測試：pnpm test
- 只跑單一檔案：pnpm vitest run src/utils/date.test.ts
- 只跑名稱符合的測試：pnpm vitest run -t 邊界
- 修改行為時，同步補上或更新對應測試
- 送出前執行 pnpm lint 與 pnpm test，失敗先修再交

## 程式碼風格
- TypeScript strict 模式，不為了過編譯放寬既有型別
- 縮排 2 格，字串用單引號，行尾不加分號
- 新的 API 處理函式放在 src/api/handlers/ 底下
- 註解與 commit 訊息用繁體中文

## 提交與 PR
- commit 格式：type(scope): 中文描述，如 fix(auth): 修正 token 更新邏輯
- PR 標題前面加套件名，如 [payments] 新增退款欄位
- 動到資料庫 schema 時，在 PR 說明列出 migration 順序

## 資安與禁區
- 絕對不 commit .env 與任何金鑰
- migrations/ 底下既有檔案只加不改
- src/legacy/ 是待重寫區，除非任務明確要求，不要動

## 工具專屬備註
- Codex：沙盒連不到內網資源，需要時先停下來問
- Claude Code：涉及 src/billing/ 的變更，先進 plan mode 討論

範本裡每一段都有存在理由。「環境與常用指令」是最有價值的一段，因為 agent 拿到可執行指令就能自我驗證；「測試」段的送出前檢查，配合 agent 會主動執行測試指令的行為，等於把驗收閉環寫進檔案。「資安與禁區」放絕對不能碰的東西，語氣可以直白，這不是客氣的地方。「工具專屬備註」是給多工具團隊的緩衝區：某個工具特有的行為約定放這裡，工具專屬段落要明寫適用工具，並檢查是否與通用規則衝突。

OpenAI 官方的 Codex 入門影片從 08:12 示範 AGENTS.md 的寫法與使用模式，可對照上方範本。

想看更多真實範例，官方建議直接上 GitHub 程式碼搜尋，用 path:AGENTS.md 過濾掉 fork 與封存專案，能翻到數萬份現成檔案；官網也點名 openai/codex、apache/airflow、temporalio/sdk-java 這些大型專案的 AGENTS.md 當參考。看別人怎麼寫很快，但抄襲前記得回到自己的專案脈絡：他們的測試指令與禁區，跟你的專案沒有關係。

寫得會被遵守：具體、可驗證、短

同一個意圖的兩種寫法，遵循效果差很多。原則是具體到可驗證：agent 要能拿你的規則當自我檢查的標準，你事後也要有基準看它有沒有做到。

模糊的寫法	具體的寫法
把程式碼整理乾淨	縮排 2 格，送出前跑 pnpm lint
記得測試	送出前執行 pnpm test，失敗先修再交
檔案放整齊	新的 API handler 放 src/api/handlers/ 底下

一條規則的長成過程：從模糊到可驗證

拿一條真實會出現的規則看它怎麼演化。第一版通常長這樣：「程式碼要保持整潔」。立意良善，但 agent 沒有檢查標準，整潔的定義每次都重新猜。第二版補上可執行的指令：「送出前跑 pnpm lint 與 pnpm test」。到這裡已經可驗證，跑了沒過就是沒做到，agent 也會自己發現失敗回頭修。第三版再補上結構約定：「新增的 API handler 放 src/api/handlers/，命名用動詞開頭，並補一個 404 案例的測試」。

每一版多出來的東西，都不是修辭，是檢查點：第二版給了機器可執行的驗收，第三版給了事後可核對的位置與命名。反過來看，如果一條規則寫完之後，你說不出「違反它會看到什麼」，那它對 agent 大概也不構成約束，值得改寫或刪掉。這個標準比任何範本都可靠，因為它直接對應模型使用規則的方式。

長度要有紀律。AGENTS.md 本身沒有官方行數上限，但兩個現實約束擺在眼前：Codex 的合併上限預設 32 KiB，超過就停止收錄；而 context 是每次 session 都要付的固定成本，檔案裡每多一行，留給程式碼與對話的空間就少一行，規則一多，每一條分到的注意力也變薄。修剪時對每一行問同一個問題：刪掉這行，agent 會開始出錯嗎？不會就刪。

兩條規則打架時，模型可能任意挑一條遵循，Claude 官方文件對這一點寫得最直白。定期把整份檔案重讀一遍，特別是巢狀多份的 monorepo：根目錄說測試跑 vitest，子目錄又說跑 jest，兩者都「對」的時候就是都錯。維護節奏前面提過，事故驅動最省力：agent 踩坑一次補一條，比憑空想一份完美文件實際。

一條硬規則怎麼樣都要放在心上：任何金鑰、帳密、token 都不進 AGENTS.md。這份檔案會進版控、會被團隊每個人看到、會進入模型的 context，它不是放機密的地方，跟 .env 不進 repo 是同一條紀律。

從零開始：用 /init 生成草稿再手工補

不想從空白檔案開始，opencode 的 /init 前面提過，會掃描專案生成或就地改善 AGENTS.md；Claude Code 的 /init 生成的是 CLAUDE.md，草稿內容照樣可以整段搬進 AGENTS.md，再用一行匯入接回去。生成的永遠是起點：模型猜得到的東西它寫得出來，但「上層目錄那份 override 是歷史共業」「某個指令要加特定環境變數」這類在地知識，只有你知道。草稿生成後把這些補進去，檔案才真正開始有價值。

多工具並存：AGENTS.md 與 CLAUDE.md、GEMINI.md、copilot-instructions.md、skills 的取捨

真實專案的痛點很少是「選哪個檔案」，而是四種檔案已經同時存在：早期就採用 Claude Code 的團隊有 CLAUDE.md，Gemini 的使用者有 GEMINI.md，GitHub 的重度使用者有 copilot-instructions.md，後來又聽說 AGENTS.md 是標準。全部保留，規則會在四個地方漂移；全部搬家，又怕某個工具讀不到。這一節把取捨講清楚。

AGENTS.md vs CLAUDE.md：專屬記憶系統與跨工具標準

本質差異一句話：CLAUDE.md 是 Claude Code 的一環，屬於它自己的四層記憶系統，有匯入語法、auto memory 這些配套；AGENTS.md 是獨立於任何工具的開放標準，一份內容所有支援的工具都能讀。單工具團隊用哪個都行，CLAUDE.md 的分層與路徑規則甚至更細；團隊裡只要有人用第二個工具，AGENTS.md 的優勢就出現了，規則不必維護兩份。

Claude Code 對兩者的處理前面講過：有 CLAUDE.md 就只讀 CLAUDE.md，都沒有才讀 AGENTS.md。所以既有 CLAUDE.md 的專案不必刪檔案，官方配方是在 CLAUDE.md 加一行 @AGENTS.md 匯入，通用規則放 AGENTS.md、Claude 專屬指示寫在匯入下方，一份內容兩邊都吃得到。要不要反過來把 CLAUDE.md 收掉併入 AGENTS.md，取決於你們還有多少 Claude 專屬的規則，多就留著，少就收掉。

AGENTS.md vs GEMINI.md：改個設定就並存

Gemini CLI 預設只認 GEMINI.md，但 context.fileName 接受清單，把 AGENTS.md 加進去之後，兩份會串接載入。實務上最乾淨的分工是：通用規則全放 AGENTS.md，GEMINI.md 只留 Gemini 特有的偏好，甚至清空。這比維護兩份內容重複的檔案安全得多，規則漂移通常就是從「兩邊都改了、只改了一邊」開始。

AGENTS.md vs copilot-instructions.md：影響範圍不同

這兩份的差異主要在相容工具與套用機制。copilot-instructions.md 放 .github/ 目錄，是 GitHub Copilot 的儲存庫指示檔；AGENTS.md 是跨工具格式，在 Copilot cloud agent、部分 Chat 與 code review 環境也有支援，細節以GitHub 官方支援表為準。建議的分工：通用專案規範放 AGENTS.md，Copilot 專屬規則放 copilot-instructions.md，再確認團隊使用環境是否支援。兩者可以在同一個儲存庫並存，Copilot 會依支援的指示機制讀取；重複或相反的規則仍要整理。

AGENTS.md vs skills.md 與 SKILL.md：名稱撞車的兩種東西

搜尋「AGENTS.md vs skills.md」的人，很可能把兩個不相干的東西當成了同類。先講 SKILL.md：它是 Agent Skills 開放標準的檔案，Claude Code 的 skills 說明頁明說這套 skills 實作遵循該跨工具標準，每個技能一個資料夾、一份帶 YAML frontmatter 的 SKILL.md，用途是打包可重複使用的流程。流程的封裝與載入也可參考Agent Skills 的載入與自製方式。它與 AGENTS.md 的分工很清楚：AGENTS.md 保存專案指示，依工具的啟動或目錄存取規則載入；skill 是隨需載入的能力包，可以由使用者指定，也能由模型判斷與任務相關後載入。專案如何工作寫前者，發佈流程怎麼跑寫後者，兩者是互補不是競爭。

再講 skills.md 這個網域：skills.md 網站是 Hasna 這家公司經營的託管技能服務，讓 agent 透過 MCP 呼叫雲端執行的技能，有免費額度與按次計費。它是產品，不是規格，跟 AGENTS.md 沒有標準層級的競爭關係。把它跟 AGENTS.md 放在一起比較，就像比較 npm 與 README：一個是取得能力的市集，一個是你專案裡的說明文件。

單一真相檔：三種做法與一個建議

整理成一份權威檔案，常見做法有三種，各有適用場景。做法一是匯入：CLAUDE.md 只寫 @AGENTS.md 一行，Claude 專屬內容寫下方，這是 Claude Code 官方給的配方，跨平台最穩。做法二是符號連結，ln -s AGENTS.md CLAUDE.md，檔案系統層級等價，但 Windows 團隊會踩到權限與 checkout 問題，官方不建議跨平台專案用。做法三是設定檔名，Gemini CLI 的 context.fileName 與 Codex 的 project_doc_fallback_filenames 都能讓工具直接認其他檔名，適合不想多建任何檔案的團隊。

你已經有的檔案	建議處置
只有 CLAUDE.md	通用規則搬到 AGENTS.md，CLAUDE.md 留一行 @AGENTS.md 匯入加 Claude 專屬指示
只有 GEMINI.md	通用規則搬到 AGENTS.md，context.fileName 列入兩個檔名
只有 copilot-instructions.md	通用規則搬到 AGENTS.md，原本檔案縮減為 GitHub 專屬規則
三種都有	AGENTS.md 當唯一權威，其餘檔案退化為匯入或專屬設定，逐一清掉重複內容

搬遷可以分步進行：先備份既有指示檔，再把通用內容整理到 AGENTS.md；CLAUDE.md 加上 @AGENTS.md 匯入，Gemini CLI 設定 context.fileName，各工具另保留必要的專屬規則。確認載入路徑與實際任務行為後，才清掉舊檔的重複內容。只寫「最新規則見 AGENTS.md」不等於設定匯入；保留備份，發現問題時才有明確的回退點。

會在同樣幾個工具之間長期搖擺的團隊，決策可以更乾脆：工具怎麼選是另一個問題，Codex 與 Claude Code 的深度比較專文談過各自適合的任務型態；但檔案策略不必跟著工具選擇一起搖擺。AGENTS.md 當主檔、專屬檔當薄薄的轉接頭，是今天各家文件都支撐得住的中間路線，未來換工具或加工具，搬的只是轉接頭，不是規則本體。

界線與維護：AGENTS.md 解決不了的事

把期待放對位置。AGENTS.md 是被當成 context 的建議，不是強制設定，這一點各家文件的口徑一致：官方規格明講使用者的即時指示覆寫檔案內容，工具文件也提醒遵循率隨指令品質浮動。它擅長的是把「需要重複交代的事」變成常識，讓 agent 大多數時候做對；它不擅長的是保證。絕對不能發生的事，交給對的層：Claude Code 的權限與安全設定、hooks，以及 Codex 的核准與沙盒設定、CI 的強制檢查，這些才是硬邊界。說明檔負責教，強制層負責擋，兩層都要有。

維護面把它當程式碼對待：進版控、進 code review、變更有意義地寫進 commit。誰都能改，改壞了看得到歷史。評估它的效果也用工程方法：agent 行為跑掉時，先確認檔案有沒有被載入（Codex 問它總結指示、Claude Code 看 /memory 或 /context、Gemini CLI 看 /memory show），再檢查規則是否互相矛盾或太長被截斷，而不是急著加重語氣。語氣從來不是問題，具體與一致才是。

OpenAI 的提示詞與技能整理建議也提醒使用者重新檢查 AGENTS.md、skills 和既有長指令。先刪掉過時或互相衝突的規則，再評估需要保留哪些常駐內容。

入門不必有儀式感。今天就可以在儲存庫根目錄放一份十行的 AGENTS.md：怎麼裝、怎麼跑測試、一條禁區。下一次 agent 動工前它就在場，之後每次踩坑補一條，一個月後你會有一份比任何範本都貼合專案的規則檔，之後換工具時，先確認載入條件，通用規則仍可維持同一份。

常見問題

AGENTS.md 是什麼？

AGENTS.md 是一份放在儲存庫裡的 Markdown 說明檔，內容寫給 coding agent 讀，定位是「給 agent 的 README」。它記錄專案的建置與測試指令、程式碼慣例、地雷與禁區，讓 agent 在動工前先取得這些 context。格式就是標準 Markdown，沒有必填欄位，規格由 Linux Foundation 之下的 Agentic AI Foundation 治理。

AGENTS.md 要放在哪裡？

基本位置是儲存庫根目錄，檔名精確是全部大寫的 AGENTS.md。monorepo 可以在各套件目錄再放巢狀的 AGENTS.md，常見約定是較近的局部規則優先，但是否自動發現及何時載入，仍須看各工具與版本。部分工具還支援全域位置，例如 Codex 的 ~/.codex/AGENTS.md 與 opencode 的 ~/.config/opencode/AGENTS.md，放跨專案的個人規則。

AGENTS.md 怎麼寫？有規定格式嗎？

沒有規定格式，就是標準 Markdown，標題隨你用。官方建議的章節包括專案概述、建置與測試指令、程式碼風格、測試說明與資安考量，判斷標準是「你會告訴新隊友的事」。寫作原則是具體、可驗證、簡短：與其寫「記得測試」，不如寫「送出前執行 pnpm test，失敗先修再交」。

agent.md 少一個 s 也有效嗎？

標準檔名是複數的 AGENTS.md，只放 agent.md 對多數工具來說等於沒放。還在用單數 AGENT.md 的專案，官方給的搬家方式是改名成 AGENTS.md 之後，再建一個指向它的符號連結維持舊路徑相容，寫死舊檔名的腳本就不會斷。新專案直接用 AGENTS.md 命名即可。

哪些工具支援 AGENTS.md？

依 AGENTS.md 官網採用清單，支援工具包含 OpenAI Codex、Gemini CLI、Cursor、opencode、GitHub Copilot coding agent、VS Code、Windsurf、Junie、Zed、Warp、Devin、Aider、goose、Jules 等 20 多個，Claude Code 也從 2.1.277 版起原生支援。支援程度不同：多數原生就讀，Claude Code 在沒有 CLAUDE.md 時直接讀，Gemini CLI 需要把 context.fileName 指到 AGENTS.md。

AGENTS.md 和 CLAUDE.md 有什麼不同？

CLAUDE.md 是 Claude Code 專屬的記憶檔，有自己的四層結構與匯入語法；AGENTS.md 是跨工具標準，一份檔案給所有支援的工具讀。兩者在 Claude Code 的優先序是：工作目錄與上層有任何 CLAUDE.md 或 CLAUDE.local.md 時，預設只讀 CLAUDE.md；都沒有時直接讀 AGENTS.md。想兩者並讀，要在設定裡把 Project instructions 調成 claude-md-and-agents-md。

Claude Code 會直接讀 AGENTS.md 嗎？

會，但有條件。Claude Code 從 2.1.277 版起原生支援：工作目錄與其上層都沒有 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 時，session 開始會自動載入沿途的 AGENTS.md，子目錄的 AGENTS.md 則在讀到該目錄檔案時按需載入。既有的 CLAUDE.md 可以用 @AGENTS.md 匯入同一份內容，這是官方給的並存配方。

AGENTS.md 和 skills.md 是同一種東西嗎？

不是。常被拿來一起討論的 skills.md 有兩種意思：一是 Claude Code 的 SKILL.md，放在 .claude/skills/ 底下、帶 YAML frontmatter、隨需載入，與 AGENTS.md 的常駐專案說明互補而非競爭；二是網域 skills.md 上的託管技能服務，與 AGENTS.md 規格無關。AGENTS.md 放「這個專案如何工作」，SKILL.md 放「某個流程怎麼執行」。

AGENTS.md 和 copilot-instructions.md 有什麼差別？

copilot-instructions.md 是 GitHub Copilot 的儲存庫指示檔，放在 .github/ 目錄；AGENTS.md 是跨工具格式。兩者在 Copilot 的支援範圍依 Chat、cloud agent、code review 與使用環境而異，AGENTS.md 並非只供 cloud agent 使用。用 AGENTS.md 當主檔、copilot-instructions.md 放 GitHub 生態專用的規則，兩者在同一個 repo 可以並存。

AGENTS.md 可以用中文寫嗎？

可以。AGENTS.md 的內容就是給模型讀的文字，中文、英文或混合都行，模型對中文的理解足以支撐全中文的規則檔。指令名稱、檔案路徑與程式語法保留原文，模型對原文術語的辨識最穩定；用詞維持一致、指令動詞明確，遵循效果就會好。

寫在 AGENTS.md 裡的規則 agent 一定會遵守嗎？

不一定。AGENTS.md 是被當成 context 的建議，不是強制設定，官方也明講使用者在對話裡的明確指示會覆寫檔案內容。遵循率會隨檔案膨脹與指令模糊而下降，規則互相矛盾時模型可能任意挑一條。必須阻擋的操作，要另外設定適用的 hooks、工具權限與 CI 檢查。

已經有 CLAUDE.md 和 GEMINI.md 的專案怎麼導入 AGENTS.md？

把跨工具通用的內容整理進根目錄的 AGENTS.md，既有檔案用三種方式銜接：在 CLAUDE.md 裡加 @AGENTS.md 匯入、把 Gemini CLI 的 context.fileName 加上 AGENTS.md，或直接把通用規則搬家後縮小既有檔案。工具選擇與檔案策略沒有綁定，先讓通用規則有一份權威版本，再讓各工具的專屬檔案退居輔助。