AGENTS.md 怎麼寫？規則寫越多，Agent 反而越貴？（2026 完整教學＋範例）

AGENTS.md 越寫越長，Agent 卻沒有比較聽話？這篇帶你搞懂該寫什麼、不該寫什麼，還附一份 30 行範例，照著改就能用！

讓 Agent 接手一個 repo，多數人做的第一件事是寫規則檔：AGENTS.md，或 Claude Code 的 CLAUDE.md。工具也鼓勵你這樣做，Claude Code 和 Codex 都有 /init，一個指令就讓 Agent 掃過整個專案，自己寫出一份。於是規則檔越長越大：專案簡介、資料夾逐一說明、程式風格、測試方法，再加上每次踩過的坑。

2026 年 2 月，ETH Zurich 和 LogicStar.ai 的研究團隊發表了第一份認真的對照實驗：同一批任務，給 Agent 規則檔和不給規則檔，各跑一次。結果是，給了規則檔，任務成功率沒有普遍提高，推論成本平均多了兩成以上。

那規則檔還要不要寫？要，但寫法要換。我的判斷是：AGENTS.md 只寫 Agent 自己查不到的事；能被機器檢查的規則，交給測試、lint、hooks。一條規則該放哪裡，可以依序問三個問題。

這張圖的重點在順序：先問 Agent 查不查得到，再問機器擋不擋得住，最後才問要不要寫進規則檔。多數人寫規則檔的順序剛好相反，想到什麼就先寫進去。下面一關一關看，接著看研究證據，最後給一份範例和檢查方法。

快速回答 一條規則要不要寫進 AGENTS.md，依序問三題：Agent 讀專案自己查得到嗎？測試、lint 或 hooks 擋得住嗎？每個任務都需要嗎？前兩題都是否、第三題是，才寫進去；其他的交給機器，或放到用得到的地方，例如子資料夾。ETH Zurich 2026 年的對照實驗裡，給了規則檔，任務成功率沒有普遍提高，推論成本平均多了兩成以上。

用三個問題篩選規則：查得到的免寫、擋得住的交給機器，剩下的才進 AGENTS.md

第一關：Agent 自己查得到嗎？專案用 TypeScript、測試放在 tests/、套件管理用 pnpm，這些讀 package.json、tsconfig.json 和資料夾結構就知道。Coding agent 本來就會先搜尋、開檔案，把這些再寫一遍，只是讓同一件事在 context 裡出現兩次。資料夾逐一介紹也屬於這一類。ETH 那份研究檢查過：規則檔裡寫了專案概覽，Agent 找到相關檔案的速度並沒有變快。

第二關：機器檢查得了嗎？縮排、import 順序交給 formatter；「UI 層不准直接呼叫資料庫」可以寫成 lint 規則或結構測試；「不要改已經合併的 migration」可以用 hook 擋。理由很直接：規則檔只是 Agent 讀到的一段文字。Anthropic 的文件寫得很清楚，Claude 把 CLAUDE.md 當成 context 參考，不當成強制設定；要不管 Claude 怎麼想都擋得住，得用 hook。Hook 是你寫的一支小程式，Claude Code 在固定時機一定會執行它，例如每次改完檔案、每次執行指令之前。

第三關：每個任務都需要嗎？怎麼跑單一測試、金額要用整數存、哪個資料夾還有外部客戶在呼叫，這種不管改哪裡都得先知道的事，才寫進根目錄的 AGENTS.md。只跟某個模組有關的規則，放進那個資料夾自己的 AGENTS.md，或做成 skill，等 Agent 需要時再讀；AGENTS.md 只留一行告訴它去哪裡找。「為什麼這樣設計」的歷史決定，寫成架構決策紀錄（ADR，一份決策一個檔案，標明狀態是否還有效），同樣用一行連結指過去。

這三關的順序有意義。越早被篩掉的規則，維護成本越低：Agent 查得到的事不用維護，機器擋得住的事不怕被忘記。真正留在 AGENTS.md 的，通常比你以為的少很多。

ETH 對照實驗：給了規則檔推論成本多兩成，任務成功率卻沒有顯著提高

ETH 這份研究叫〈Evaluating AGENTS.md〉。它用了兩組任務：一組是常見的 SWE-bench Lite，300 題，來自 11 個熱門 Python 專案，這些專案本來沒有規則檔，所以只測工具 /init 生成的版本；另一組是研究團隊自己收集的 138 題，來自 12 個本來就有 AGENTS.md 或 CLAUDE.md 的 Python 專案，可以比較「不給」「LLM 生成」「開發者自己寫」三種情況。Agent 有四組：Claude Code 配 Sonnet 4.5、Codex 配 GPT-5.2 和 GPT-5.1 mini，以及 Qwen Code 配 Qwen3-30B。

為什麼會這樣？論文的解釋，對寫規則檔的人很有用。

第一，Agent 很聽話。規則檔裡提到某個工具，Agent 就真的去用：寫了 uv 的專案，Agent 平均每題用 1.6 次，沒寫的幾乎不用。寫了「改完要跑完整測試」，它就多跑測試、多搜尋、多開檔案。每一條指令都會變成額外的步驟，步驟多了，成本就上去，但這些步驟不一定和眼前的任務有關。

第二，內容重複。研究團隊把專案裡的 README、範例和 docs/ 都刪掉，再給同一份 LLM 生成的規則檔，成功率反而平均高了 2.7%。換句話說，/init 生出來的規則檔，大部分是在重講 repo 裡本來就有的東西。

所以論文的建議是：暫時不要用 LLM 自動生成規則檔；人寫的規則檔，只寫 README 裡沒有的事，例如專案特有的慣例，或效能、安全這類非功能需求。

這份研究有它的邊界：只測 Python、每個條件只跑一次。另一份 2026 年 1 月的研究看了 10 個 repo、124 個 PR，發現有 AGENTS.md 時，Agent 的執行時間中位數少了約 29%，輸出 token 少了約 17%，完成率差不多。兩份研究並不矛盾：規則檔本身沒有好壞，好壞看裡面寫了什麼。寫了 Agent 查不到的捷徑，它少繞路；寫了它本來就知道的事，它多讀一遍，還可能照著做一堆不必要的檢查。

順帶一提，這篇論文的第一版摘要寫的是「傾向降低成功率」，網路上流傳的「降 3%」也出自第一版。後來的版本加了統計檢定，改成「沒有普遍提高」。我採用的是後者。

規則檔長度控制在百行以內：只寫讀程式碼看不出的坑與邊界，其餘指向文件

長度。Anthropic 對 CLAUDE.md 的建議是每份 200 行以內，越長越佔 context，Claude 遵守得也越差。Codex 會把從根目錄一路到工作目錄的 AGENTS.md 串起來，預設上限是 32 KiB，超過的部分直接不讀。

OpenAI 自己的經驗更極端。2026 年 2 月，OpenAI 工程師 Ryan Lopopolo 在〈Harness engineering〉裡寫，他們的團隊用 Codex 寫出一個約一百萬行的產品，人沒有手寫一行程式。過程中他們試過「一份大 AGENTS.md」，失敗的原因他列了四點：context 是稀缺資源，大檔案會擠掉任務本身；什麼都標重要，等於什麼都不重要；它一寫完就開始過時；一大塊文字沒辦法用機器檢查。最後他們把 AGENTS.md 縮到大約一百行，當成目錄，指向 docs/ 裡分門別類的文件。他的說法是：給 Codex 一張地圖，不要給它一千頁的操作手冊。

同一篇文章裡，Lopopolo 用一張圖說明 docs/ 為什麼要存在：Codex 看不到的知識，對它來說就不存在。Google 文件裡的規劃、Slack 上的決定、某個人腦中的架構方向，都得寫成 repo 裡的 Markdown，AGENTS.md 這張地圖才有地方可以指。

該寫的。對照 Anthropic 的官方建議與 GitHub 分析兩千五百多份 agents.md 的整理，值得寫進去的有這幾類：

• Agent 猜不到的指令，尤其是怎麼跑單一測試、送出前要跑哪個檢查
• 和語言預設不同的慣例
• 環境的怪癖，例如必要的環境變數、本機資料庫怎麼起
• 讀程式碼看不出來的坑
• 邊界：哪些事直接做、哪些先問、哪些不准做
• 指路：哪一類工作去讀哪一份文件

實際上大家寫的，和這張清單有落差。一份分析 2,303 份規則檔的研究發現，寫實作細節與架構的各約七成，寫安全與效能這類非功能需求的只有一成五左右。前者 Agent 讀程式碼大多看得到，後者才是它最可能不知道的事。

不該寫的。讀程式碼就知道的事、語言通用慣例、逐檔說明、常變動的資訊、長篇教學，以及「寫乾淨的程式」這種沒辦法驗證的話。Anthropic 的最佳實務文件給了一個好用的刪減標準：每一行都問，刪掉它，Claude 會不會犯錯？不會，就刪。

下面是一份 29 行的範例。專案是示意的，一個用 Next.js 和 PostgreSQL 做的訂閱制網站：

# AGENTS.md

訂閱制網站：Next.js、PostgreSQL。這份檔案只寫讀程式碼看不出來的事。

## 指令
- 安裝：`pnpm install`（lockfile 是 pnpm 的，不要用 npm）
- 跑單一測試：`pnpm test -- src/billing/refund.test.ts`
- 送 PR 前：`pnpm check`（型別、lint、測試一次跑完）
- 本機資料庫：`docker compose up db`，第一次先跑 `pnpm db:seed`

## 不明顯的坑
- 資料庫一律存 UTC，換成台灣時間只在 `src/lib/time.ts` 做
- `src/legacy/` 是舊版 API，還有外部客戶在呼叫：只修 bug，不重構
- 金額用整數「分」存，不用浮點數
- 測試裡寄信一律走假的寄信服務，真的寄要設 `MAIL_LIVE=1`

## 邊界
- 直接做：改 `src/` 與對應測試、新增 migration
- 先問：新增或升級依賴、改 CI 設定、刪檔案
- 不做：改已經合併的 migration、把 `.env` 的內容貼到任何地方

## 要深入時讀哪裡
- 金流與退款：`docs/payments.md`
- 為什麼這樣設計：`docs/adr/`（每份決策標了狀態）
- 前端元件：`src/components/AGENTS.md`

## 完成的定義
- `pnpm check` 全綠，新功能的測試在功能壞掉時會變紅
- PR 說明寫清楚改了什麼、怎麼驗證

這份範例裡沒有專案簡介，沒有資料夾逐一介紹，也沒有程式風格。風格交給 formatter，結構 Agent 自己會看。每一行都是讀程式碼看不出來的事，而且大多能被驗證：指令跑不跑得起來、路徑存不存在，都查得到。

範例裡有一行要特別說：「不要改已經合併的 migration」。寫在 AGENTS.md，是讓 Agent 知道；要讓它做不到，還得加一道 hook。這兩層不衝突，前者讓它少走冤枉路，後者在它還是走錯時擋下來。

能由機器檢查的規則交給 Linter、Hooks 與 CI：機器能擋住的事，不必寫進文字檔

能被機器檢查的規則，有三個常見的去處。

Formatter 和 linter。風格類的規則全部交給它們。Lopopolo 的團隊更進一步，把架構規則也寫成自訂 lint：每個業務模組只能依固定的層次往下依賴，違反就報錯。他們還特別把 lint 的錯誤訊息寫成「怎麼修」，Agent 撞到時，錯誤訊息本身就是修正指引。他們的原則是：文件不夠用的時候，就把規則升級成程式碼。

Hooks。Claude Code 的官方範例是改完檔案就自動跑 Prettier，寫在專案的 .claude/settings.json：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

從此「格式要對」這條規則不必出現在 AGENTS.md 裡，Agent 也不必花 token 去想它。擋危險指令、保護不能改的檔案，用的是執行前的 PreToolUse hook，寫法可以看〈Claude Code 權限要怎麼設？一直按「允許」真的安全嗎？（2026 完整懶人包）〉。

測試與 CI。最後一道關卡，對所有人和所有 Agent 都一樣。前提是測試本身可信：AI 寫的測試可能在功能根本沒跑時照樣通過。測試怎麼變得可信，可以接著讀〈AI 寫的測試全過，為什麼功能還是錯的？驗證閉環完整懶人包（2026）〉。

跨工具共用設定：在 CLAUDE.md 匯入 @AGENTS.md，並用符號連結共用 Skills

AGENTS.md 是 OpenAI 在 2025 年 8 月和 Amp、Google Jules、Cursor、Factory 等團隊一起推出的格式，就是一份普通的 Markdown，沒有規定欄位。2025 年 12 月，它和 MCP、goose 一起成為 Linux Foundation 新成立的 Agentic AI Foundation 的創始專案，官方說已有超過六萬個開源專案在用。日本的 @IT 報導這件事時，形容它是「讓專案專屬的指引能被一致提供的標準約定」。

各家讀它的方式不太一樣，這是最容易踩坑的地方：

Claude Code 那一列的陷阱很常見：你為了放自己的私人設定加了一份 CLAUDE.local.md，Claude Code 就默默不讀團隊的 AGENTS.md 了。最穩的寫法是讓 CLAUDE.md 只負責匯入，Claude 專屬的規則寫在匯入那行下面。官方文件說，就算新版已經會自己讀 AGENTS.md，保留這行匯入也不會讀兩次。

Skills 也一樣。Codex 和多數工具讀 .agents/skills/，Claude Code 只讀 .claude/skills/。用符號連結指到同一份，就只需要維護一個資料夾：

# CLAUDE.md only imports the shared rules; Claude-only notes go below this line
printf '@AGENTS.md\n' > CLAUDE.md
# One skills folder for every tool
mkdir -p .agents/skills .claude && ln -s ../.agents/skills .claude/skills

避免規則檔過時：用 CI 腳本檢查路徑是否存在，並開新 Session 抽測 Agent

規則檔最常見的死法是過時：資料夾改名了、文件搬家了，規則檔還指著舊路徑，Agent 照著走就撞牆。這件事可以交給機器。

下面這支小程式想驗證兩件事：規則檔裡用反引號標出、看起來像路徑的字，都還存在；規則檔沒有超過行數上限。前提是你習慣把路徑寫在反引號裡，上限設 150 行，可以自己調。

#!/usr/bin/env python3
"""Check AGENTS.md: every path it mentions still exists, and the file stays short."""
import re
import sys
from pathlib import Path

MAX_LINES = 150
path = Path(sys.argv[1] if len(sys.argv) > 1 else "AGENTS.md")
text = path.read_text(encoding="utf-8")
problems = []

lines = len(text.splitlines())
if lines > MAX_LINES:
    problems.append(f"{lines} lines, over the {MAX_LINES}-line limit")

# Paths are written in backticks and contain a slash: `src/lib/time.ts`, `docs/adr/`
for token in re.findall(r"`([^`]+)`", text):
    for word in token.split():
        if "/" in word and not word.startswith(("http", "-")):
            if not (path.parent / word).exists():
                problems.append(f"missing path: {word}")

print("\n".join(problems) or f"ok ({lines} lines)")
sys.exit(1 if problems else 0)

把上面的範例 AGENTS.md 放進一個空資料夾跑，它會列出七個不存在的路徑，從 src/billing/refund.test.ts 到 src/components/AGENTS.md，並以失敗結束；把這些檔案建出來再跑一次，就只印出 ok (29 lines)。放進 CI 或 pre-commit，資料夾一改名，規則檔就會跟著被抓出來。Claude Code 另外有 /doctor prompt-audit，會找出規則檔裡指向不存在的檔案、互相矛盾或已經過時的寫法，但它只出報告，不會自己改。

還有一個不用寫程式的檢查：開一個新的 session，不給任何提示，問 Agent 三個問題：怎麼跑單一測試？哪些檔案不能改？這個專案最容易踩的坑是什麼？答得出來，代表規則檔有被讀到、也寫得夠清楚。答不出來，先看它到底有沒有載入這份檔案，Agent 在下決定那一刻看到什麼，〈Context Engineering 是什麼？Agent 一直犯同樣的錯怎麼辦？（2026 完整懶人包）〉有完整的排查方法。

規則檔的邊界：商業與架構取捨由人把關，查不到且擋不住的才進 AGENTS.md

模型越來越強，規則檔需要的份量會再往下掉。Anthropic 在 2026 年 7 月說，他們替 Claude 5 世代的模型刪掉了 Claude Code 八成以上的系統提示，內部的 coding 評測沒有可量測的退步；他們給的 CLAUDE.md 建議也是一樣的方向：保持輕量，大部分篇幅留給程式碼裡的坑，不要寫 Agent 看檔案就知道的事。

有些規則機器檢查不了，也不適合寫進規則檔。產品該長什麼樣、哪個功能值得做、這次的取捨對不對，這些要寫在需求文件與 review 裡，由人判斷。規則檔只能讓 Agent 少走錯路，替不了這些判斷。

小專案不必照搬這整套。一個人的 side project，AGENTS.md 十行就夠，hook 一支都不用；等到你發現自己在對話裡第三次提醒同一件事，再決定它該進規則檔，還是該變成一個檢查。

規則檔常讓 Agent 變貴、成功率卻沒有跟著提高，原因就在這裡。要讓它第一天就找得到規則，規則檔反而要短。它第一天讀到的，應該是一百行以內、只講它查不到的事；其他的，要嘛它自己讀得到，要嘛一碰就會被機器擋下來。

查得到的不寫，擋得住的交給機器，剩下的才進 AGENTS.md。

常見問題

可以用 /init 讓 Agent 自動生成 AGENTS.md 嗎？

ETH 的研究建議暫時不要。Claude Code 和 Codex 的 /init 一個指令就能生成規則檔，但生成的內容大多在重講 README、範例和 docs/ 裡本來就有的東西；研究團隊把這些文件刪掉後，再給同一份生成的規則檔，成功率反而平均高了 2.7%。人寫的版本只寫 README 裡沒有的事。

AGENTS.md 和 CLAUDE.md 要各寫一份嗎？

不用。在 CLAUDE.md 第一行寫 @AGENTS.md，匯入共用規則；Claude 專屬的規則寫在這行下面。要注意 Claude Code 只要讀到任何 CLAUDE.md 或 CLAUDE.local.md，預設就不讀 AGENTS.md，所以這行匯入要保留。

寫進 AGENTS.md 的禁止事項，Agent 一定會遵守嗎？

不一定。規則檔只是 Agent 讀到的一段文字，Anthropic 的文件也說，Claude 只把 CLAUDE.md 當成 context 參考。要不管 Agent 怎麼想都擋得住，例如不准改已經合併的 migration，要用 hook、lint 或 CI。

怎麼確認 AGENTS.md 有被讀到？

開一個新的 session，不給任何提示，問 Agent：怎麼跑單一測試？哪些檔案不能改？這個專案最容易踩的坑是什麼？答不出來，先確認它有沒有載入這份檔案。規則檔也會過時：資料夾改名了，檔案還指著舊路徑。可以在 CI 加一支小程式，檢查規則檔裡的路徑都還存在、行數沒有超過上限。

AGENTS.md 要寫多長？

Anthropic 建議 CLAUDE.md 每份 200 行以內，越長越佔 context，Claude 遵守得也越差。OpenAI 的團隊試過一份大 AGENTS.md，後來縮到約一百行，當成指向 docs/ 的目錄。查得到的不寫、擋得住的交給機器，剩下的通常比你以為的少很多。

延伸閱讀

• Context Engineering 是什麼？Agent 一直犯同樣的錯怎麼辦？（2026 完整懶人包）
• Claude Code、Codex、Gemini CLI 怎麼選？2026 三大 AI Coding 工具完整比較
• Claude Code 權限要怎麼設？一直按「允許」真的安全嗎？（2026 完整懶人包）
• AI 寫的測試全過，為什麼功能還是錯的？驗證閉環完整懶人包（2026）
• Plan、Build、Verify、Ship 是什麼？AI 寫程式變快後，進度要怎麼算？（2026 完整懶人包）

參考資料

研究

• Thibaud Gloaguen, Niels Mündler-Sasahara, Mark Niklas Müller, Veselin Raychev, Martin Vechev（ETH Zurich、LogicStar.ai）, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?（arXiv 2602.11988，v1 2026-02-12，v3 2026-09-29；本文數字取自 v3） https://arxiv.org/abs/2602.11988
• Lulla et al., On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents（arXiv 2601.20404，2026-01-28） https://arxiv.org/abs/2601.20404
• Chatlatanagulchai et al., Agent READMEs: An Empirical Study of Context Files for Agentic Coding（arXiv 2511.12884，v2 2026-08-09） https://arxiv.org/abs/2511.12884

官方文件與工程文章

• Ryan Lopopolo (OpenAI), Harness engineering: leveraging Codex in an agent-first world（2026-02-11） https://openai.com/index/harness-engineering/
• Anthropic, How Claude remembers your project（Claude Code 文件，2026-10-16 檢視） https://code.claude.com/docs/en/memory
• Anthropic, Best practices for Claude Code（2026-10-16 檢視） https://code.claude.com/docs/en/best-practices
• Anthropic, Automate actions with hooks（2026-10-16 檢視） https://code.claude.com/docs/en/hooks-guide
• Thariq Shihipar (Anthropic), The new rules of context engineering for Claude 5 generation models（2026-07-24） https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
• OpenAI, Custom instructions with AGENTS.md（Codex 文件，2026-10-16 檢視） https://learn.chatgpt.com/docs/agent-configuration/agents-md
• Google, Provide context with GEMINI.md files（Gemini CLI 文件，2026-10-16 檢視） https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md
• Agent Skills, Specification（2026-10-16 檢視） https://agentskills.io/specification
• Matt Nigh (GitHub), How to write a great agents.md: Lessons from over 2,500 repositories（2025-11-19） https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
• Michael Nygard, Documenting Architecture Decisions（2011-11-15） https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

標準與報導

• AGENTS.md（2026-10-16 檢視） https://agents.md/
• Linux Foundation, Linux Foundation Announces the Formation of the Agentic AI Foundation（2025-12-09） https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation
• @IT（ITmedia）,〈Agentic AI Foundation（AAIF）発足　寄贈されたMCP、AGENTS.md、gooseはどうなるのか〉（2025-12-16，日文） https://atmarkit.itmedia.co.jp/ait/articles/2512/16/news047.html