最近 AGENTS.md (在 Claude Code 是 CLAUDE.md、Cursor 是 .cursorrules) 怎麼寫的討論變多了。這個檔案就是丟進每次工作階段的「使用手冊」，告訴 coding agent 這個專案怎麼一回事、要遵守什麼規矩。它已經由 Anthropic、Google、Microsoft、OpenAI 等主要成員一起捐給 Linux Foundation 的 Agentic AI Foundation，成為跨工具的開放標準，agents.md 上宣稱已經有 6 萬個 repo 在用。

但要怎麼寫才有效? 二月初蘇黎世聯邦理工學院出了篇論文得到一個反直覺結論，在 X 上被 Theo、Matt Pocock 等大 V 放大講成「AGENTS.md 反而會害你」，引發後續一堆討論。實際上比這更微妙。小編把研究、作者本人的澄清、反對聲音，加上社群歸納的實務建議，整理一下。

1. 反直覺結果: LLM 自動生成的 AGENTS.md 反而會降低成功率

蘇黎世聯邦理工學院 LogicStar 團隊的這篇論文做了大規模實驗。他們在 SWE-bench Lite 跟自建的 AgentBench (138 個任務、12 個有 context file 的 repo) 上跑 Claude Code、Codex、Qwen Code 三套 agent，測試三種設定: 沒有 context file、用 agent 內建的 /init 自動生成、開發者手寫的。

結果:

  • LLM 自動生成的: 平均降低 3% 成功率，但增加 20% 推論成本 (多 2-4 步操作)
  • 開發者手寫的: 只有微弱的正向效果 (~4%)，但同樣會增加成本
  • 不論用什麼模型生 (Claude Sonnet 4.5、GPT-5.2、Qwen3-30B-Coder)、用什麼 prompt (Codex 的、Claude Code 的)，結論都差不多

換句話說: 如果你是直接 /init 出來的 CLAUDE.md，可能比沒有更糟。

2. 為什麼會這樣? 不是 agent 不聽話，是它太聽話

這篇論文有意思的地方是它做了追蹤分析。發現有 context file 的時候:

  • agent 跑更多測試 (pytest 多用)
  • 探索更多檔案 (grep、read 多)
  • 推理 token 多 22%
  • 但找到第一個相關檔案的步數沒有變少 — 這顛覆了「context file 是專案地圖」的假設

研究團隊也檢查了 agent 對指令的依從度: 被寫進 AGENTS.md 的工具，使用次數會從幾乎為零跳到平均每次任務 1.6-2.5 次。Phil Schmid 在 X 上的整理算了一個更直觀的數字: 提到的工具被使用機率高 160 倍。

所以重點是: agent 確實會遵守 AGENTS.md 裡的指令，問題是寫進去的「不必要指令」反而讓任務變複雜。

編按: 還有一個諷刺的發現 — 研究團隊把 repo 裡所有 .md、docs/、範例程式碼都刪掉之後，LLM 自動生成的 context file 才開始發揮正面效果。意思是這些自動產生的內容很大程度上就是在重複既有文件而已。難怪寫了等於白寫。

3. 該寫什麼? WHAT / WHY / HOW

Phil Schmid 根據這篇研究歸納成三塊:

  • WHAT (是什麼): 技術棧、專案結構、各部分做什麼。Monorepo 特別重要 (因為 agent 不容易自己摸出來)
  • WHY (為什麼): 專案目的、關鍵元件存在的理由。幫 agent 理解意圖而不只是結構
  • HOW (怎麼做): 怎麼建置、測試、驗證變更。特別是非預期的工具鏈 — 例如這個專案用 uv 而不是 pip、用 bun 而不是 npm

一個更精確的判準是: 如果這件事 agent 自己讀程式碼就能發現，那就不用寫。值得寫的東西反過來都是 agent 沒辦法從程式碼推出來的 — 非預期的工具鏈選擇、歷史包袱、團隊共識、外部約束、踩過的雷。

4. 不該寫什麼? 大多數人塞進去的其實沒幫助

研究團隊的追蹤分析跟社群觀察意外一致 — 自動生成的 AGENTS.md 最常包但最沒用的就是這幾類:

  • 重述 README 跟既有文件的內容: 研究最諷刺的發現 — 把 repo 裡所有 .md 跟 docs/ 刪掉之後，LLM 自動產生的 AGENTS.md 才開始有正面效果。換句話說大部分自動產生的內容只是在「複述既有文件」，等於白寫
  • 大段架構概覽 / 目錄列表: 100% 的 LLM 自動產生 AGENTS.md 都會包這種「我們的架構分三層、handler 處理 X、service 處理 Y…」，但研究數據顯示這對 agent 找對檔案的速度沒有任何改善。Agent 一個 ls 就能拼出結構，不需要你告訴它
  • 看得到的技術棧細節: package.json、pyproject.toml 已經寫了，agent 看得到。「我們用 React」是廢話，「我們用 React 18 但 hooks 走自己的 wrapper」才有價值
  • 程式風格規定: 「用 4 空格縮排」、「camelCase 命名」這種規則交給 linter / formatter 處理，比塞進 AGENTS.md 便宜、確定、不吃上下文配額。記得前面提的數字: 模型可靠順從上限約 150-200 條指令，別拿來寫 linter 做得更好的事
  • 空泛的標語: 「寫 clean code」、「good naming」、「performance matters」這種話，模型訓練資料裡一堆，寫了等於沒寫，還佔順從度配額
  • 詳細 API 文件: 用連結帶到外部文件就好，不要把整個 API table 貼進來
  • 只在特定情境才用到的指令: 「部署時要先 X」、「跑 e2e 測試前要 Y」這種任務指令應該分到專門的子檔案，用條件區塊或 import 帶進來，不要塞在主檔讓每次工作階段都看
  • 自動 /init 出來不修就放著: 這篇研究最直接的結論。/init 預設會包前面所有「沒幫助」的內容，平均降 3% 成功率、增 20% 成本

研究最後的 takeaway 句子蠻一針見血: 「人寫的 context file 應該只描述最低限度的需求」。多寫不會加分，反而扣分。

5. 反過來看: 作者本人的澄清，跟方法論上的爭議

論文紅了之後，作者 Thibaud Gloaguen 在 LinkedIn 上親自貼了一篇，點名 Theo 跟 Matt Pocock 把研究結論講歪了。他重申:

我們證明的是 LLM 自動生成的 AGENTS.md (例如 Claude Code 的 /init) 沒有提升任務完成率，而且讓 agent 行為變得更「吵」。但簡潔的、人寫的 AGENTS.md 是可以幫到 coding agent 的。重點在於: 如果你決定要在每次互動前都加上某些指令，先問自己這些指令對你大多數任務真的需要嗎? 如果不是，看情況再加上去可能更好。

也就是說，真正的反派是 /init 跟「塞越多越好」的心態，不是 AGENTS.md 本身。

幾個值得提的反對跟補充意見:

  • 研究選的 repo 樣本可能有偏差: InfoQ 報導裡有開發者留言指出，研究選的 repo 大多是「最近的 LLM 周邊小型隨興開發專案」，AGENTS.md 品質本來就參差。對於有大量領域知識、未公開的中大型專案，「人寫的高品質 AGENTS.md」價值會大很多
  • 只測測試通過率，沒測程式品質: LinkedIn 留言裡有個重要追問 — 如果 agent 把測試弄綠了，但完全忽略專案命名規範跟架構慣例，這篇研究是看不出來的。換個評估指標可能整個結論都不一樣
  • Vercel 的案例反而證實有效: the-decoder.com 提到 Vercel 在「教 agent 它訓練資料裡沒有的最新 Next.js 知識」這個情境下，context file 效果非常顯著。研究測的是「修一般 bug」這種 agent 早就知道怎麼做的任務，自然看不出來
  • 寫 AGENTS.md 的副效果是逼你思考: 另一條 InfoQ 留言寫得蠻誠實: 「我維護 CLAUDE.md 三個月了，效果比想像中明顯，但不是因為它真的給了什麼 context — 而是寫的過程逼你把腦袋裡的隱性知識 (『這個怪 pattern 是因為 Y 的歷史包袱』) 講清楚。寫下來之後 agent 接收到了，新進工程師也接收到了。」

編按: 還有一個有趣的同時期論文 Lulla et al. 結論看似衝突: 它測出 AGENTS.md 反而讓中位執行時間降 28%、輸出 token 降 17%。Sulat Substack 的解析點出兩篇其實沒衝突 — Lulla 測的是「agent 多快瀏覽 codebase」(效率)，Gloaguen 測的是「agent 有沒有真的解出來」(正確性)。Context file 讓 agent 找路找得快，但不見得讓 agent 答得對。

6. GitHub 從 2500+ repos 學到什麼?

GitHub 的這篇觀察了跨 Claude Code、Codex、Copilot 的 2500 多個 agents.md，歸納出 5 個原則 (其實跟前面論文呼應):

  1. 可執行指令放前面 — npm test、pytest -v 這種 agent 會反覆查的東西，放開頭最容易被找到
  2. 程式碼範例 > 長篇解釋 — 一個示範你 codebase 風格的真實片段，勝過幾段抽象描述
  3. 明確的邊界 — 三層: 永遠要做、要先問、絕對不要做。最常見也最有用的一條: 「絕對不要 commit secrets」
  4. 具體的技術棧細節 — 不要寫「React 專案」，要寫「React 18 + TypeScript + Vite + Tailwind CSS」並標版本
  5. 6 個核心領域: 指令、測試、專案結構、程式風格、git 工作流、邊界

7. 為什麼 Claude 會忽略你的 CLAUDE.md?

HumanLayer 的 Dex Horthy 寫了一篇蠻關鍵的觀察: Claude Code 的系統提示詞會把 CLAUDE.md 包在一個 <system_reminder> 裡，並明確告訴模型「以下內容可能跟你的任務相關，也可能不相關」。

這就是為什麼當你的 CLAUDE.md 越寫越長，agent 會越來越常忽略某些段落 — 它真的會主動過濾。

他的解法是用條件區塊把場景特定的指令包起來:

<important if="writing or modifying tests">
- Use createTestApp() helper for integration tests
- Mock database with dbMock
</important>

不要把所有東西都包，核心東西 (技術棧、目錄結構、專案身分) 還是要常駐。但測試、部署這種只在特定場景才用得到的，加上條件就比較不會被當成可選的。

另一篇 HumanLayer 的《Writing a good CLAUDE.md》有個更狠的數字: 前緣模型大概只能可靠遵守 150-200 條指令，Claude Code 自己的系統提示已經吃掉約 50 條，所以你的空間其實沒那麼多。HumanLayer 自己的 CLAUDE.md 只有 60 行。

8. 大專案怎麼辦? 不要寫一份大檔，要分層

當你的 AGENTS.md 超過 150-200 行，社群普遍建議改用模組化:

  • 每個子目錄一份 AGENTS.md: Codex CLI、Cursor、Copilot 都支援階層式合併 — agent 在 packages/api/ 工作時，會把根目錄、中間層、和 packages/api/AGENTS.md 都讀進來。OpenAI 自己的 Codex repo 就用了 88 個 AGENTS.md，monorepo 每個服務一份
  • import 語法: Claude Code 支援 @agent_docs/database.md 這種引用，把領域特定的指引拆出去，主檔只放路標
  • 跨工具用 symlink: 多工具團隊常見做法 — 寫一份 AGENTS.md 當作唯一來源，CLAUDE.md、.cursorrules 都用 symlink 指過去，不要維護平行版本

更極端的做法是有獨立開發者用 Claude Code 蓋 10.8 萬行 C# 系統時演化出的三層架構: 一份 660 行的「constitution」永遠載入、19 個領域子 agent 按需呼叫、34 份規格文件透過 MCP server 檢索。這篇 Codified Context 論文的核心觀念是「文件是 agent 依賴的基礎建設，過期就會出錯，要當程式碼一樣維護」 — 對 monorepo 跟複雜 codebase 是個值得參考的模型。

9. 真正的紅線要靠 hooks，不能只靠 CLAUDE.md

redreamality 的這篇深度整理有個常被忽略的數字: 即便寫得再好，CLAUDE.md 規則的順從率大約只有 70%。

意思是「絕對不能做的事」如果只寫在 CLAUDE.md 裡，會有三成機率 agent 還是會做。所以社群的成熟做法是把規則分兩層:

  • CLAUDE.md (建議性): 寫慣例、偏好、流程 — 70% 的順從率夠用了
  • .claude/settings.json 的 hooks (機械性): 真正的硬規則寫在這裡。例如 PreToolUse 回 exit code 2 是唯一能真的攔下 agent 動作的方式。「不能 push 到 main」、「edit 後一定要 lint」這種事用 hook 寫，不是放在 CLAUDE.md 裡許願

這也呼應 redreamality 那篇蠻精準的一句框架:

寫 CLAUDE.md 的時候，你不是在寫一段 prompt，你是在寫一個系統的執行期變數。

它每次工作階段都會跟任務、時間、其他上下文互動，不是靜態文字。把它從 100 行砍到 80 行不是排版，是在重構。

小編的綜整

這幾篇加起來其實在講同一件事的不同層次:

  • 預設保持精簡 — 目標 300 行以內，能用 60 行更好。每一行都會吃掉每次工作階段的上下文，要值得
  • 重點寫「不寫就會錯的東西」 — 用 uv 不是 pip、用 bun 不是 npm，這種非預期的工具鏈比結構概覽有用得多
  • 寫偏好比寫事實有價值 — Ben Tossell 那篇的觀點蠻一致: 技術棧跟結構 agent 自己摸得到，但「測試完再給我網址」、「用 Exa 不要用內建 search」這種行為偏好它摸不到
  • 採漸進式揭露 — 主檔案放路標，細節分到 agent_docs/ 或子 agent。對複雜專案甚至要走到三層架構搭配 MCP 檢索
  • 不要 /init 出來就放著 — 數據顯示自動產生的會降低成功率，要人工修
  • 真正的紅線用 hooks，不要許願 — CLAUDE.md 是建議，hooks 才是強制
  • 把文件當基礎建設，不是 README — 文件過期 agent 就會錯，要納入維護週期

最有啟發的一點是: 寫 CLAUDE.md 的本質，是在跟一個「每次都失憶但會完全相信文件」的 agent 工作。你不是在寫給未來會加入團隊的工程師看，是在設計一個 agent 在開始工作前的記憶植入。這個視角換過來，什麼該寫、什麼不該寫，自然就清楚了。