前陣子有一份來自 ETH Zurich 的研究預印本（2026/2/12），標題很直白——《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》（評估 AGENTS.md：儲存庫層級的脈絡檔案對程式編寫 Agents 有幫助嗎？）。簡單來說，就是在問：我們幫 程式編寫 agent 準備的那些 AGENTS.md、CLAUDE.md，到底有沒有幫到忙？
結論蠻反直覺的。
報告說了什麼？
研究團隊針對四組主流 程式撰寫 agent（Claude Code + Sonnet-4.5、Codex + GPT-5.2、Codex + GPT-5.1 Mini、Qwen Code + Qwen3-30B），在 SWE-BENCH LITE 和他們自建的 AGENTBENCH 上做了系統性測試。測試分三種情境：完全沒有 脈絡檔案（context file）、用 LLM 自動生成的 脈絡檔案、以及開發者手寫的 脈絡檔案。
結果是：
- LLM 自動生成的 脈絡檔案，平均降低任務成功率 2-3%，同時推高推論成本超過 20%
- 開發者手寫的 脈絡檔案 稍好，平均提升約 4%，但一樣增加了步驟數和成本
- Agent 確實會遵循 脈絡檔案 裡的指令——所以問題不出在 指令遵循（instruction following）
- 有趣的是，推理 token（reasoning token）增加了 14-22%，代表模型自己也「覺得」任務變難了
換句話說，業界大力推薦的「幫你的 repo 加個 AGENTS.md 吧！」這件事，至少在這份研究的範圍內，效果相當可疑。
不過這裡要先說清楚一個重要前提：這份研究測試的全部是既有的成熟 Python 專案——django、ansible、transformers 這類已經有完整程式碼、測試套件、文件結構的 程式碼庫（codebase）。在「全新專案」或「文件不完整的 程式碼庫」上，結論可能完全不同。事實上，當研究者把 repo 裡所有既有文件（README、docs/、範例程式碼）都移除之後，LLM 生成的 脈絡檔案 反而開始有正面效果了。
所以，脈絡檔案 不是「沒用」，而是「在資訊已經充足的情況下，它更像是噪音」。
但為什麼會是噪音？
報告的歸因停在「冗餘」和「不必要的要求讓任務變難」，這沒錯，但我覺得還可以再深一層。
先回到 CLAUDE.md 這類文件的實際運作機制。根據 Anthropic 官方文件，CLAUDE.md 的內容會被直接載入系統提示詞（system prompt），在 agent 開始工作之前就已經存在於它的 上下文 裡。而且在指令優先級上，CLAUDE.md 的地位高於使用者的一般提示——也就是說，它不只是「參考資料」，它是「系統層級的規則」。
相對地，repo 裡的其他文件（程式碼、SDD、一般文件），是 agent 在工作過程中透過工具呼叫主動去讀取的。Agent 帶著當下的任務脈絡去找、去讀、去理解。
這兩件事性質上非常不同。
讀 脈絡檔案，比較像是接收「別人的結論」——它告訴 agent「這個 repo 的架構是 A→B→C」，agent 接收的是一個已經被壓扁的線性敘事。而解析程式碼，是 agent 自己在建構理解——追蹤 import、看 function signature、理解 class 繼承、感受 資料流（data flow）。前者是照字面接收，後者更像是一種立體的、拓撲式的認知建構。
問題來了：當這兩種理解方式產生衝突時，agent 會怎麼做？
由於 脈絡檔案 被放在系統提示詞裡、有更高的指令優先級，agent 的預設行為是傾向信任它。但程式碼的「真相」需要 agent 自己去推導。如果 脈絡檔案 說「認證邏輯在 auth/ 目錄下」，但實際上已經重構到 middleware/ 了，agent 需要先讀到 middleware/ 的 程式碼、自己推斷出這是認證邏輯、然後才能判斷 脈絡檔案 是過時的。這個推導過程比直接相信 脈絡檔案 的成本高很多。
而且更隱蔽的情況是：脈絡檔案 可能不是「錯」，而是用一種特定的方式描述了 程式碼庫，而這個描述方式跟 agent 在直接讀程式碼時自然形成的理解不同。這時候不是誰對誰錯，而是兩套認知地圖在打架。
將在外，軍令有所不從
如果我們把 脈絡檔案 當成一種「行為規範」，把解析程式碼當成「臨場反應」——那這就是一個經典的「將在外，軍令有所不從」的處境。
軍令（即 脈絡檔案）在什麼時候最有價值？是在將領還沒到戰場、還不了解地形的時候。一旦將領已經在前線、已經掌握了實際狀況，軍令如果跟現場不符，最好的做法就是「不從」。
但目前 編寫程式碼的 agent 的 harness 設計，幾乎不允許「不從」。脈絡檔案 被放在系統提示詞的高優先級位置，agent 的預設行為是服從，而不是根據自己對 程式碼 的理解去覆寫。這等於是一個制度上強迫前線將領永遠聽軍令的系統。
而且這裡有一個弔詭的三重負擔：
- 讀 脈絡檔案 本身要花成本
- 正常解析程式碼也要花成本
- 確認兩者之間沒有矛盾，又是一層成本
第三層是最隱蔽也最浪費的，因為如果沒有 脈絡檔案，它根本不存在。報告裡那 20% 的成本增加和 22% 的 推理 token 增長，一個可能的解釋就是 agent 花了大量資源在做「軍令」和「戰場實況」之間的比對和調和。
報告裡還有一個細節可以佐證這個觀點：GPT-5.1 Mini 會花好幾個步驟去反覆尋找和重複閱讀 脈絡檔案，而且只有在 脈絡檔案 存在時才出現這個行為。一個將領在前線不斷翻閱軍令——它在不確定的時候不是去看 程式碼（戰場），而是回去看 脈絡檔案（軍令），尋求指示。
那 脈絡檔案（context file）到底應該放什麼？
如果順著「將在外」的邏輯，答案就比較清楚了：
CLAUDE.md / AGENTS.md 適合放的是「戰前簡報」——也就是 agent 還沒碰到 程式碼 之前就需要知道、而且從 code 本身推導不出來的事。比如：
- 這個專案用
uv不用pip - 測試用
pytest跑要加什麼參數 - commit 訊息 的格式規範
- 「設計規格請參考
docs/SDD.md」（路標，不是內容搬運）
這些是環境設定和作業規範——不知道的話會直接卡住或犯錯。
專案架構、模組職責、設計決策這些東西，放在 repo 裡的一般參考文件更合適。 原因有兩個：第一，agent 讀這些資訊是帶著具體任務去讀的，它會根據當下的需要去篩選和理解，而不是一開始就被迫全部消化。第二，這類資訊會隨著專案演進而改變，放在普通文件裡更新的心理門檻低很多。
簡單來說，CLAUDE.md 放「怎麼在這裡工作」，參考文件放「這個東西是什麼、要變成什麼」。一個管行為規範，一個管認知素材。前者越短越好，後者可以豐富但由 agent 自己按需取用。
脈絡檔案 應該是「戰前簡報」而不是「作戰命令」——提供背景、給出初始方向，但把戰術層面的判斷交給前線。
寫在最後
要再次強調，這些觀點是基於報告數據和已確認的技術機制所做的推論和解讀，不是報告本身的結論。報告測試的是既有成熟 Python 專案的情境，而且只測了「脈絡檔案 有或沒有」的影響，並沒有測試「極簡 脈絡檔案 + 豐富的 repo 內參考文件」這種組合。
不過我覺得，光是「把資訊放在不同位置，agent 會用不同方式處理它」這件事，就值得我們在使用 程式撰寫 agent 時多想一下。不是資訊越多越好，也不是把什麼都塞進 CLAUDE.md 就叫做「幫 agent 準備好上下文」。
畢竟，給前線將領一份二十頁的作戰手冊，跟給他一份兩行的戰略意圖加上一張詳細的地圖——哪個更有可能打贏？
答案應該不用我說吧？～
參考資訊：
- Gloaguen, T., Mündler, N., Müller, M., Raychev, V., & Vechev, M. (2026). Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? arXiv:2602.11988v1 https://arxiv.org/abs/2602.11988
- Anthropic. Using CLAUDE.md files: Customizing Claude Code for your codebase https://claude.com/blog/using-claude-md-files
- Anthropic. How Claude Code works https://code.claude.com/docs/en/how-claude-code-works
