AGENTS.md 對上 CLAUDE.md：我量了自己 948 行的設定檔後決定的拆法
AGENTS.md 已經進 Linux Foundation，但 Claude Code 到 2026 年 8 月仍只讀 CLAUDE.md。官方認可的匯入與符號連結兩種接法差在哪、Windows 為什麼會卡、我這個 repo 948 行的設定檔哪些該砍哪些該搬走，附一張四層分層表。
💡 本文是我對照官方文件重量自己 repo 設定檔的紀錄。給同時用兩種以上 AI coding agent、被多份設定檔搞混的人。
目錄
1. 一個 repo 到底要放幾份 agent 設定檔？
小提示
- 設定檔的問題從來不是「格式選哪個」，是「同一條規則被寫在三個地方，然後三個地方開始不一致」
- 動手之前先跑 wc -l 量一下自己的檔案。多數人低估了自己寫了多少
2. AGENTS.md 是什麼、現在誰在管它
-
2025-12-09 進基金會
OpenAI 把 AGENTS.md 捐給 Linux Foundation 底下新成立的 Agentic AI Foundation，跟 Anthropic 捐的 MCP、Block 捐的 goose 同一批創始專案
-
同批的 MCP 有多大
MCP 官方部落格在同一篇公告裡給的數字是每月 9,700 萬次 SDK 下載、10,000 個活躍 server。AGENTS.md 是被放在這個量級的隔壁
-
格式刻意做得很笨
沒有 schema、沒有 frontmatter、沒有必填欄位。官方範例只給三個區塊：開發環境提示、測試指令、PR 規則
-
專案自治
MCP 那篇公告寫明基金會負責治理，個別專案對技術方向與日常維運保有完全自主權。換句話說格式不會因為進基金會就被委員會改掉
小提示
- 「沒有 schema」是特色不是缺點 —— 它讓每家 agent 都能宣稱支援，門檻只有「會讀 Markdown」
- 要判斷一個約定是不是真標準，看的是誰在維護它，不是看有幾篇教學文
3. Claude Code 為什麼到 2026 年 8 月還是只讀 CLAUDE.md
-
issue #31005 仍然開著
2026-03-05 開的，到 8/30 我看的時候還是 open 狀態，訴求是同時支援 AGENTS.md 與 .agents/skills/
-
3,020 個 upvote
它引用的前案 #6235 累積 3,020 個 upvote、224 則留言。以單一 issue 來說這是很大的量體
-
issue 作者的指控
該 issue 內文寫，前後 6 個相關 issue 沒有一個得到 Anthropic 的人回覆。這是提出者的說法，我照原文轉述
-
被點名的反諷
Agent Skills 標準本身是 Anthropic 訂的，但 Claude Code 讀的是 .claude/skills/ 而不是標準裡的 .agents/skills/
小提示
- 不要把「官方沒做」讀成「官方不建議」—— 文件裡是主動教你怎麼接 AGENTS.md 的
- 追這種功能與其等，不如先用官方認可的接法，之後原生支援上線也不用改
4. 官方文件給的三種接法，差別在哪
| 接法 | 怎麼做 | 適合 | 限制 |
|---|---|---|---|
| 匯入 | CLAUDE.md 第一行寫 @AGENTS.md，下面再接 Claude 專屬段落 | 還想寫 Claude 才吃的規則，例如某個目錄一律走 plan mode | 多維護一個檔案；匯入最多 4 層 |
| 符號連結 | ln -s AGENTS.md CLAUDE.md | 完全不需要工具專屬內容，追求只有一份實體檔 | Windows 要系統管理員權限或開發者模式 |
| 一次性匯入指令 | /import，把別家 agent 的設定複製進對應的 CLAUDE.md | 從 Cursor、Copilot 搬家，順便把 MCP server 與 skills 帶過來 | 需要 Claude Code v2.1.213 以上；是複製不是連動 |
小提示
- 接完之後開新 session 跑 /context，看 Memory files 清單裡有沒有它。沒出現就是沒載到，別靠感覺判斷
- 團隊有 Windows 成員就統一走 @AGENTS.md 匯入，省掉「只有我這台不會動」的來回
5. 我這個 repo 的實況：948 行對上官方建議的 200 行
-
可以從 codebase 推出來的
目錄結構樹、7 個站點與色碼的對照表、API 端點清單。agent 自己 ls 一下就有，這類最該砍
-
只有踩過才知道的
翻譯字串裡的單引號會打爆 JS、砍站只刪 nginx block 不刪 DNS 會變成整站鏡像。這類再長都該留
-
跨工具都適用的規則
測試怎麼跑、commit 前要過哪幾關、絕不 git add -A。這批是 AGENTS.md 的正主
-
只有 Claude Code 吃得到的
子 agent 並行怎麼拆、worktree 隔離、skill 的觸發設定。這批只能留在 CLAUDE.md
小提示
- Claude Code v2.1.206 起 /doctor 有 trim 檢查，會主動建議砍掉能從 codebase 推得的段落，先跑它比自己糾結快
- 判斷一段該不該留，問自己「新同事讀完 code 會不會自己知道」。會，就砍
6. 分層表：哪一條規則該放哪個檔
| 放哪裡 | 內容 | 誰讀得到 | 何時載入 |
|---|---|---|---|
| AGENTS.md | build 與測試指令、程式風格、命名慣例、PR 規則 | Codex、Cursor、Copilot coding agent 等 | 每個 session 開場 |
| CLAUDE.md | 第一行 @AGENTS.md，下面接 Claude 專屬的工作方式 | 只有 Claude Code | 每個 session 開場 |
| .claude/rules/*.md | 帶 paths frontmatter 的規則，例如只在動 API handler 時生效的驗證要求 | 只有 Claude Code | 讀到符合 glob 的檔案時 |
| .claude/skills/ | 多步驟流程，例如發文產線、上線前檢查 | 只有 Claude Code | 被叫到或判定相關時 |
小提示
- rules 支援 paths glob 條件載入，這是唯一真正能把長設定檔瘦下來的機制
- 我這個 repo 的 19 個 skill 就是靠「只在被叫到時載入」把流程細節擋在 context 外面，設定檔本身反而該更薄
7. 我在設定檔上犯過的 4 個錯
-
❌ 把最會出事的規則寫在第 300 行
這個 repo 的 CLAUDE.md 自己記著一條教訓：Django 註解印在 header 上，同一個錯犯了兩次。長檔中段的規則就是會被稀釋。現在改成兩件事 —— 會影響線上畫面的規則往前挪，並且加 e2e 迴歸測試守著，那份守門測試現在有 57 項
-
❌ 以為 @AGENTS.md 匯入能省 context
官方文件寫得很直白：被匯入的檔案在啟動時照樣展開進 context。匯入換來的是單一事實來源，不是更小的 context。真要省得靠 rules 的條件載入或 skills
-
❌ 想用一行 symlink 一勞永逸
官方自己就註明 Windows 建符號連結需要系統管理員權限或開發者模式。團隊只要有一台 Windows，這條路就會變成「只有我這台不會動」的支援工單
-
❌ 把架構全景當成設定檔在寫
我那 948 行裡有一大塊是目錄樹、站點表、端點清單，全是 agent 自己讀得到的。這類內容佔著每個 session 的開場 context，卻沒改變任何行為
小提示
- 設定檔的品質指標不是行數，是「同一個錯有沒有犯第二次」
- 每次 code review 抓到 agent 不該犯的錯，就回頭問一句：這條規則當初寫在哪一行
注意事項
若用 ln -sf 強制建立符號連結，原本的 CLAUDE.md 會被直接取代且不留備份，動手前請先確認它已經 commit 進版控。
8. 最後
小提示
- 延伸閱讀：Claude Code 的完整工作流、Skills 建立教學、MCP 2026-07-28 規格大改，站內都有整理
9. 資料來源與擷取日期
這篇的每個數字都來自下面幾個一手來源，擷取日期都標了，你可以自己去對：
- Claude Code 官方文件 — How Claude remembers your project（2026-08-30 擷取。AGENTS.md 段落、@import 語法、200 行建議、4 MiB 上限、/doctor trim 檢查、/import 需 v2.1.213 以上）
- anthropics/claude-code issue #31005 — Support for AGENTS.md and .agents/skills/（2026-08-30 擷取。2026-03-05 開啟、仍 open、引用 #6235 的 3,020 upvote 與 224 則留言）
- openai/agents.md — a simple, open format for guiding coding agents（2026-08-30 擷取。24.0k star、1.8k fork、MIT 授權、範例區塊）
- MCP 官方部落格 — MCP joins the Agentic AI Foundation（2026-08-30 擷取。2025-12-09 公告、AGENTS.md 與 goose 同批創始專案、每月 9,700 萬次 SDK 下載、10,000 個活躍 server）
這幾個數字換版本就會變，尤其是 star 數與 issue 狀態。我會隨 Claude Code 版本更新回來改。
重點整理
- 1 AGENTS.md 由 OpenAI 在 2025-12-09 捐給 Linux Foundation 底下的 Agentic AI Foundation，跟 MCP、goose 是同一批創始專案。
- 2 Claude Code 到 2026 年 8 月仍然只讀 CLAUDE.md，官方文件給的兩條路是在 CLAUDE.md 第一行寫 @AGENTS.md 匯入，或用 ln -s AGENTS.md CLAUDE.md 建符號連結。
- 3 要求原生支援的 issue #31005 從 2026-03-05 開到現在還沒關，它引用的 #6235 累積 3,020 個 upvote 與 224 則留言。
- 4 官方對 CLAUDE.md 的長度建議是 200 行以內、超過 4 MiB 直接跳過不讀；我這個 repo 的 CLAUDE.md 是 948 行、46,377 bytes。
- 5 我對照後的分法是三層：跨工具規則放 AGENTS.md、Claude 專屬放 CLAUDE.md、只在特定路徑生效的搬進 .claude/rules/ 的 paths frontmatter。
相關連結
從覺得 CLI AI 怪到現在離不開。實測 Plan mode、subagents、hooks、background tasks，含我家的 CLAUDE.md 完整範本。
SKILL.md 寫法、觸發條件設計、參數處理與測試優化。設定檔瘦身之後，流程細節該搬去哪就看這篇。
跟 AGENTS.md 同一批進 Agentic AI Foundation 的 MCP，最新規格改了哪些、既有 server 要怎麼跟上。
設定檔管不住的規則就交給 hooks。事件驅動機制與 8 個實用 Hook 範例。
同時用多家 agent 的真實情況，也是需要一份跨工具設定檔的起因。
相關懶人包
2026 AI 投資趨勢指南：從晶片到應用，掌握 AI 產業鏈投資機會
AI 浪潮正在重塑全球投資市場。從 NVIDIA 到台積電，從雲端服務到 AI 應用，全面解析 AI 相關投資標的與風險
2026 AI 簡報工具完全攻略：10 分鐘做出專業簡報的秘密武器
比較 2026 年最好用的 AI 簡報工具：Gamma、Beautiful.ai、Canva AI、GenPPT、Plus AI，含免費方案、價格、實測心得與選擇建議。
2026 AI 簡報工具完全比較：Gamma、Tome、Beautiful AI 等 8 大工具實測評比
AI 簡報工具實測：Gamma、Tome、Beautiful AI、Canva AI、Presentations AI 等 8 款工具，依需求、預算、品質完整比較，10 分鐘做出專業簡報。
一般聲明
本站提供之資訊僅供參考，不保證其完整性與正確性。使用者應自行判斷資訊之適用性。