我懶得寫 CLAUDE.md，結果這反而是對的

每次 timeline 上出現 CLAUDE.md（或 AGENTS.md）相關的文章，我都跟自己說「待會再研究」，然後就滑過去了。看著別人費心打造各種精緻的 AGENTS.md 設定，老實說有點心虛——我是不是已經落後了？

直到最近的基準測試數據出來，那種心虛感才瞬間消失。原來，我的懶，還挺有道理的。

LLM 自動產生的 context 檔案，只會讓事情更糟

「給 agent 更多 context，應該會更好吧？」我也這樣以為。

研究人員在 SWE-bench Lite 上測試 LLM 自動產生的 context 時，成功率掉了 0.5%。在 AgentBench 上，又再少了 2%。就算是人工精心撰寫的檔案，也只有 4% 的改善空間。我把這個現象叫做「context 過擬合」。

• LLM 自動產生的 context 在 SWE-bench Lite 上讓成功率下降 0.5%
• 在 AgentBench 上又再掉了 2%
• 推論成本增加 20–23%
• 只有在專案完全沒有文件的情況下，才觀察到 2.7% 的正向效果

Gloaguen 等人發表的論文 “Evaluating AGENTS.md” 也印證了這件事：比起完全不提供 repository context，context 檔案反而更容易讓任務成功率下滑。

Agent 太聽話了——這才是問題所在

問題不是 agent 忽視你的指令，而是剛好相反。

你在 context 檔案裡寫一行「請使用 uv」，agent 就算在完全不需要的情況下，也會去安裝、執行 uv，每次都多繞幾步。

使用 GPT-5.2 的測試中，有 context 檔案時，推論 token 增加了 14–22%。Agent 忙著照著指令走，反而分心、沒辦法專注在真正要解決的問題上。

• 不必要的 pytest 執行次數增加
• grep 和讀檔工具的使用範圍遠超過實際需求

寫「不要做 X」，Agent 反而一直想著 X

我之前在某篇文章提過 SKILL.md 內容被讀取的時機點，AGENTS.md 也有類似的問題。

它夾在 developer message 這一層，坐落在 system prompt 和 user prompt 之間。這個位置，對 agent 的推理過程影響非常大。

你寫「不要動這個檔案」，agent 反而會對那個檔案多想一次。研究人員把這個現象叫做「粉紅象效應」——你叫人不要想粉紅色大象，他腦海裡第一個浮現的就是粉紅色大象。

• 優先順序：provider 指令 → system prompt → AGENTS.md → user prompt
• 靠人工維護的檔案跟不上程式碼的迭代速度，資訊很快就過時

真的要寫，請保持最小化

如果你的專案完全沒有任何文件，context 檔案還是能發揮作用——數據顯示在這種情況下有 2.7% 的正向效果。但要寫的話，內容一定要精簡再精簡。

一行說明專案特有的 build 工具用法。 一行修正 agent 老是搞錯的某個慣例。

加上一個像「如果發現結構上有怪異之處，請立即回報」這樣的指令，agent 就會變成一個不斷回報 codebase 問題的工具。除此之外，把程式碼結構設計得更直覺，遠比寫一堆說明文字有效。

• 強化單元測試和型別檢查，效果勝過 context 檔案
• 如果檔案放的位置讓人摸不著頭緒，就直接搬移，別用文字解釋

會寫 context 檔案，不代表工程能力強。真正厲害的，是理解 context 檔案的結構原理，並在此之上設計出更好的 meta 系統。而有時候，「懶得寫」，就是你能做出最好的工程決策。