AGENTS.md 怎麼寫？從整理 CLAUDE.md 談 Agent 指令檔的最佳實務
AGENTS.md 是一個專門寫給 AI 寫碼工具（Coding Agent）看的開放格式。它用純 Markdown 寫成，放在專案裡，負責告訴 AI 這個專案該怎麼跑、有哪些寫作慣例需要遵守。 你可以把它想成是專案的 README，只是讀者從「人類」換成了 Cursor、Codex 或 Claude Code 這些會實際動手改你程式碼的 AI 工具。
前陣子我讀了 Matt Pocock 寫的〈A Complete Guide to AGENTS.md〉，順手把自己部落格專案裡的指令檔也大掃除了一番。 在這過程中踩到的坑比我想像中還多，索性把這些經驗整理成這篇文章。
AGENTS.md 到底是什麼？作用範圍怎麼分？
AGENTS.md 是 OpenAI 在 2025 年 8 月推出的開放標準，背後有 Google（Jules）、Cursor、Factory 等生態系夥伴共同參與。 到了 2025 年 12 月，它又跟 Anthropic 的 MCP、Block 的 goose 一起被捐贈到 Linux 基金會旗下新成立的 Agentic AI Foundation，正式成為跨廠商共管的標準。它的設計理念很直白：單一檔案、純 Markdown、不綁定特定工具，也沒有強制規定的欄位。官方把它定位成「給 AI 寫碼助理的 README」，官方網站一句話就解釋完了。
它的採用率成長得非常快。根據官方與社群統計，到 2025 年底已經有超過六萬個開源專案在使用，並獲得二十幾個工具支援（2026/8，可能會持續變動，看個趨勢就好）。
要真正理解它，關鍵在於搞懂「作用範圍（Scope）」。一個專案（Repo）裡可以有好幾份 AGENTS.md。 你可以把整個專案通用的規則放在根目錄，然後在不同的子目錄底下，放該範圍專屬的慣例。 當 AI 在改檔案時，愈靠近工作目錄的規則，優先權就愈高。
這樣一來，不管你是整個大型專案（Monorepo）的共通規範，還是某個套件（Package）自己的小毛病，都可以分層管理，不用全部擠在同一個檔案裡。
另外一點要釐清的是「這條規則是寫給誰的」。你個人的開發偏好（例如喜歡哪種 Git commit 風格）跟專案本身的鐵律（例如規定一定要用哪個套件管理員），兩者的性質完全不同。 如果混在一起寫，久了維護起來會非常痛苦。
同一個檔案，不同 AI 工具的讀取方式卻不一樣
雖然 AGENTS.md 是共通格式，但各家工具「怎麼載入這個檔案」卻沒有統一標準，跨工具使用時很容易在這裡踩雷。
以 OpenAI Codex 為例，它會從 Git 專案的根目錄一路往下找，把你目前工作目錄沿途的 AGENTS.md 接成一條指令鏈，愈靠近工作目錄的內容會排在愈後面、優先權也愈高。
在我寫這篇文章時，Codex 對這條合併結果有預設 32 KiB 的容量上限（由 project_doc_max_bytes 控制），超過的部分會直接被捨棄。 這在實務上代表什麼？如果你的指令檔寫得太肥，被砍掉的通常會是「最靠近你、最專屬於該目錄」的那段規則，然後你就會滿頭問號：「為什麼 Codex 都不理我的規則？」（相關細節請參考 OpenAI 官方文件）。
但 Claude Code 的作法就不一樣了。 它主要讀取自己的 CLAUDE.md，在官方文件也明說了：它不讀 AGENTS.md。
也就是說，如果你專案裡已經有一份 AGENTS.md，官方建議的橋接作法是另外建一個 CLAUDE.md，在裡面用 @AGENTS.md 語法把它匯入，或者乾脆建一個軟連結（Symlink），讓兩邊共用同一份內容，不用各寫各的。
這裡真正要搞懂的是 Claude Code 幾種載入機制的差異：CLAUDE.md 本體以及裡面用 @path 匯入的檔案，都是「預先載入」的，一打開專案就會全部塞進 AI 的對話脈絡（Context）裡。而擴充技能（Skills）則是「需要時才載入」，平常只會讓 AI 看到簡短的描述（Description），等 AI 判斷任務對得上時，才會把完整內容讀進來。我之前寫過一篇 Claude Code Skills 的整理，詳細討論過這個差異。
所以說，同一份 AGENTS.md，換個 AI 工具來讀，發現的順序、合併的規則、甚至容量上限都可能不一樣。在跨工具寫指令檔時，千萬別假設所有工具的運作方式都一模一樣。
我從自己的 CLAUDE.md 大掃除學到的事
講點實戰經驗。我這個部落格專案的作法，是把根目錄的 AGENTS.md 當作一個輕量的參照檔，裡面只寫一句「完整規範都在 CLAUDE.md」，然後把真正的內容都集中在 CLAUDE.md 裡。 這樣可以避免兩個檔案各自發展，最後內容脫節的窘境。
在讀完 Matt Pocock 的文章後，我對著自己的 CLAUDE.md 動了刀。
最明顯的「肥肉」是一份記載了十幾個檔案路徑跟用途的「核心檔案清單」。 這種清單是最容易產生「過時路徑」的高風險區：只要你搬動了檔案，AI 就會非常有自信地帶你去錯的地方。
我把這份清單砍到只剩五個真正常用的進入點，其他則改成一句「其餘請自行搜尋」，把冷門的建置腳本、部署設定交給 AI 自己去找。 有趣的是，在驗收這些留下來的路徑時，我發現其中某一條關於 Layout.vue 的描述早就過時了。
它上面寫著「用來注入 ArticleMeta」，但翻開現在的程式碼，那個元件根本不是在這裡注入的，現在的 Layout 負責的是圖片燈箱、頁尾留言以及上下篇導覽。 我一邊消滅過時的遺跡，一邊卻差點把另一條過時的描述給留下來，那麼 AI 會精神錯亂也就不是什麼意外的事情了。
幫指令檔瘦身，真正的重點是「留下來的每一條規則都必須準確」，至於路徑數量的多寡反而是其次。 既然決定要留，就要花心思維護；如果不打算維護，那還不如直接刪掉，否則錯誤的資訊反而更危險。
那到底該怎麼寫？
以下這幾個原則，是我調整完之後，會拿來檢查指令檔的標準，可能不一定正確，但提供給大家參考：
根目錄指令檔只放「普遍適用，且無法輕易從程式碼推導出來」的資訊
專案的一句話定位、該用哪個套件管理員、非標準的建置或測試指令，這些必須留著。至於某個函式在第幾行、某個元件叫什麼名字，這種搜尋一下就有的東西，就別抄進來養一份會過期的副本。每一行都要斤斤計較
會想盡量壓短，理由很現實：指令檔在一開專案時就會全部載入，每次發請求都會跟著送出，這等於是一直在跟你真正的任務搶資源額度。而且模型能穩定處理的指令量與 Context 本來就有限。 有一份 IFScale 的研究，他們測出當模型被塞入 150 到 200 條指令時，會開始明顯偏袒排在前面的那些規則。雖然這是特定任務的結果，不能直接套用所有情況，但大方向很清楚：塞得愈多，排在後面的規則愈容易被犧牲。 所以每一行都值得你問一句：「這真的是每個任務都需要的嗎？」路徑是好東西，前提是它得準確
真正會出事的是路徑過時。具體寫出「某某邏輯放在某某路徑」能讓 AI 少走很多冤枉路，但前提是它必須是準確的。我上面那個差點留著的Layout.vue過時描述就是個血淋淋的反例。留在指令檔裡的每一條路徑，都要當成「我承諾會維護它」，維護不了的就別留。同一件事說一次就好，別讓規則互相打架
當指令互相矛盾時，AI 模型會隨便挑一條來執行，而且你根本不知道它挑了哪一條。如果是會變動的資訊（如支援清單、版本、預設值），記得加上「目前」或「寫這篇文章時」當作緩衝；引用數據時也務必標註查證日期。善用漸進式揭露（Progressive Disclosure）
在決定一條規則該放哪時，我現在會先問：「是不是每個任務都需要它在場？」如果是，就放根目錄；如果只有某類檔案或特定任務才需要，就把它下放到特定範圍的規則裡，或者做成 Skill 讓它「需要時才載入」。把細節搬到「用到時才出現」的地方，才不會讓無關的任務被冗長的規則干擾。個人偏好與專案規則要分開
「我習慣用 pnpm、commit 訊息愛寫成怎樣」是你的個人偏好；「這個專案一律用 pnpm、build 前要先跑 XXX」這類命令句才是專案的鐵律。 前者放使用者層級的設定（像 Claude Code 的~/.claude/CLAUDE.md或 user-level rules），只跟著你走；後者才 commit 進 repo 的指令檔，跟著專案走。 混在同一份專案指令檔裡，下一個接手的人就得連你的個人習慣一起吞。指令檔是溝通，不是防線
還有一點很容易被忽略：必須強制的行為，別只寫在指令檔裡祈禱模型每次都乖乖聽話。該擋的用 Git Hooks、該驗證的用 CI/CD、該限制的用系統、權限設定來強硬防護處理。把指令檔當成程式碼來維護
指令檔是會腐化的：檔案路徑會搬動、寫作慣例會改變、AI 模型也會進步。請把它納入 Code Review 的流程中；如果模型重複犯同一個錯，就補上一條規則；發現過時的資訊就大膽砍掉。 我這次整理下來最大的收穫，其實是讓自己養成定期回頭審視自己指令檔的習慣。
未來的取捨
我現在這種「讓 AGENTS.md 指向 CLAUDE.md」的作法也不是唯一解，它只是在「單一維護來源」和「跨工具相容」之間，選了一個我目前用起來比較順手的方式。
反過來的做法也有人在用：讓 CLAUDE.md 把 AGENTS.md 的共通內容匯入進來，把主檔改成 AGENTS.md。這樣對只認得 AGENTS.md 的工具更友善，代價是 Claude Code 這邊會多了一層預先匯入的動作，內容照樣全部塞進對話脈絡裡，省不了多少資源。
再進階一點，還可以把部分規則搬到 Claude 的特定路徑規則，或者包裝成 Skills，讓它們真正做到「需要時才載入」。 這在單一工具的環境下非常漂亮，但一旦你的團隊同時使用 Codex 和 Claude Code，Skills 這種 Claude 專屬的機制在其他工具就無用武之地了，等於又回到了「同一套規則要為不同工具維護不同形態」的老問題。
所以這題沒有標準答案，完全取決於你的團隊實際使用哪些 AI 工具、以及願意為相容性付出多少維護成本。 先搞清楚自己是身處單一工具還是多工具的環境，再來決定策略，這絕對比盲目抄襲任何一種 best practices 都來得實在。