好的 AGENTS.md 等於免費換模型，寫錯了比沒文件更糟

原始來源與檔名：20260512_2026-05-12T093208+0800-好的 AGENTS.md 等于免费换模型，写错了比没文档更糟.md

來源：[[@freeman1266]] / X — 2026-05-09 原始檔名：2026-05-12T093208+0800-好的 AGENTS.md 等于免费换模型，写错了比没文档更糟.md

NAPKIN | 餐巾紙

餐巾紙公式

Good AGENTS.md = Claude Haiku performs like Opus. (+25% quality) Bad AGENTS.md = Over-exploration & Context Rot. (-30% quality) Rules: <150 Lines + Procedural Workflows + Decision Tables + Real Code Snippets (Paired Do/Don’t).

Augment Code 團隊針對數十份專案的 AGENTS.md (給 AI 讀的行為準則) 進行量化實測，發現一份寫得好的文件能將編碼品質提升 25%，等同於免費把輕量級模型升級成旗艦級模型；但寫錯了（過於冗長、充滿警告），反而會讓 AI 無所適從，產出比完全不寫還差。核心秘訣在於：將主文件控制在 150 行內（避免中間迷失）、將任務寫成編號工作流、使用決策表與真實程式碼片段，並且將「寫給人看的架構願景」與「寫給 AI 看的執行手冊」嚴格分開。

一句話

不要把給人類看的 README.md 內容塞進給 AI 看的 AGENTS.md 裡！實測證明，塞了幾萬字的架構說明和幾十條「禁止事項」只會讓 AI “上下文中毒”，什麼事都做不好。最頂級的 AGENTS.md 只有短短 150 行，裡面沒有廢話，全是「SOP 步驟清單」、「用哪個套件的決策表」，以及「3 行真實程式碼範例」。寫好這 150 行，你的 AI 寫 Code 能力會直接暴增 25%。

餐巾紙草圖

[ Anatomy of a Perfect AGENTS.md ]

Size: 100-150 lines (hits the Attention Sweet Spot)

Content:
1. Procedural Workflow: "Step 1, 2, 3..." (Removes ambiguity)
2. Decision Tables: "If API -> use REST; If UI -> use Zustand"
3. Paired Warnings: 
   ❌ Don't use raw HTTP.
   ✅ Use lib/http shared client.
4. Real Snippets: 3-5 lines of actual repo code.

What NOT to include:
- Architectural philosophy (put in README)
- Future unmerged patterns (confuses the Agent)

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

• 實驗震撼彈: 優秀的 AGENTS.md 能讓代碼正確性提升 25%，劣質的則會讓完整性下降 30%。
• 7 個有效模式:
  1. 漸進式披露: 主文件控制在 100~150 行，細節按需加載 (避免 Lost in the Middle)。
  2. 程序性工作流: 任務寫成編號步驟，消除 AI 猜測的歧義。
  3. 決策表: 提前決定技術選型 (React Query 還是 Zustand)，避免 AI 亂試。
  4. 真實程式碼片段: 用 3~10 行真實代碼代替偽代碼。
  5. Do & Don’t 配對: 只有警告會導致過度探索；每個「不要做」都要配上「該怎麼做」。
  6. 模組化文件: AGENTS.md 應放在特定子模組下，而非全域大雜燴。
  7. 規則要具體: 拒絕模糊的框架約定。
• 2 大失敗模式:
  1. 過度探索陷阱: 太多架構概述或警告堆疊，導致上下文中毒 (Context Rot)。
  2. 描述未來模式: 寫了還沒落地的架構，引導 Agent 尋找不存在的程式碼。
• 人類與機器的分工: README.md 寫給人看 (願景與心智模型)，AGENTS.md 寫給機器看 (規則與執行手冊)。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

1. 消除歧義 (Disambiguation): 好的 AGENTS 提升的不是模型的「智商」，而是幫助模型在巨大的代碼庫中「走對路」。程序性工作流、決策表、成對的 Do/Don’t，本質都是在收斂解空間。
2. 上下文的詛咒 (Context Rot): 給模型越多資訊不等於結果越好。當你給了 50 條警告，Agent 為了驗證這些警告，會去翻閱無數不相關的文件，最終導致核心任務的失焦與「中間迷失」效應。

關鍵證據

• Augment Code 追蹤了 Agent 的文檔發現率：AGENTS.md 的觸及率是 100%，而放在 _docs/ 裡孤立的 3 萬字安全規範，觸及率不到 10%。這證明了 AGENTS.md 是唯一具有可靠「發現性 (Discoverability)」的入口，不該被無用資訊塞滿。

邊界條件

• 維護成本極高: 既然要求使用「真實程式碼」且「描述現狀」，這份文件必然是高頻變動的。一旦 API 修改而 AGENTS 沒更新，它就會從資產變成毒藥。作者建議將其納入 Code Review Checklist，或是盡量使用檔案路徑引用而非直接複製程式碼。

ROUND 3: SOUL | 靈魂提取

“還能怎么用”

• 知識連結: 完美對照《What Apple’s Leaked CLAUDE.md Teaches Us》。蘋果的內部文件完美符合了這裡的鐵律：小於 200 行、沒有廢話、直接規定架構 (AsyncStream > Combine)、成對的禁令。
• 深層洞見: “AGENTS.md 描述現狀，不是願景。” 人類看文件時，腦補未來架構是激勵人心的；但機器看文件時，腦補未來的架構是致命的幻覺。區分「寫給人看」與「寫給機器看」的文檔，是軟體工程學的一次重要分岔。
• 行動呼籲: 打開你專案根目錄的 AGENTS.md 或 .cursorrules。
  1. 如果超過 150 行，請將細節拆分到子資料夾中。
  2. 刪除所有「未來我們將採用…」的句子。
  3. 將所有「禁止使用 XXX」的單獨句子，補上「請使用 YYY 代替」。 做到這三點，你的 AI 將立刻變得更聰明。