🔧 阿川の電商水電行
AGENTS.md 真的對 AI Coding 有用嗎？或許在此之前你沒用對？
AGENTS.md 相信大家應該不陌生，它們一般都是被放在根目錄的典型 Context Files，這些文件被默認作為 Coding Agent 的 「README」，一般是用來提供倉庫概覽、工具鏈指令、編碼規範或者設計模式等，不少 Agent 還提供 /init 之類命令自動生成這些文件。
實際上在此之前大家都是
GEMINI.md、CLAUDE.md、copilot-instructions.md之類的各自為政，而 2025 之後，OpenAI、谷歌、Cursor 和 Sourcegraph 合作制定了AGENTS.md，大家才開始統一標準。
可以說 AGENTS.md 就像是個大家都默認的必需品，根據統計，根據 2026 年的統計數據，已經有超過 60,000 個開源項目在 root 目錄下包含了 AGENTS.md 文件，但問題是，這些“ Context Files 到底能不能讓 Coding Agent 更容易把 issue/任務做對？還是只會增加 token 成本？
測試條件
論文 《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》 針對這個問題做了測試，他們採用了兩套互補數據集 + 對照設置：
- 兩個數據集
- SWE-Bench Lite：經典的 300 個 Python repo-level 任務（熱門倉庫），這些倉庫本來沒有開發者寫的 context file，論文在這裡評測“自動生成 context file”的效果。
- AGENTBENCH：他們專門去挖了 12 個帶開發者自帶 context file 的 Python 倉庫，從真實 PR/issue 裡構造出 138 個實例（bugfix + feature）
這裡 AGENTBENCH 的意義：以前 benchmark 沒趕上 AGENTS.md 流行，所以你沒法直接測真實世界開發者寫的 AGENTS.md 到底有沒有用，所以他們為此新做了數據集。
- 三種對照設置（同一任務跑三遍）
- NONE：完全不提供 context file
- LLM：按 agent 開發者推薦流程，用對應 agent 的推薦
init/提示詞自動生成 context file - HUMAN：使用倉庫裡開發者自己提交的 context file（僅 AGENTBENCH 有）
然後就是被測 agents / models，這裡採用了四套組合：
Claude Code + Sonnet-4.5，Codex + GPT-5.2 / GPT-5.1 Mini，Qwen Code + Qwen3-30B-Coder，並強調各模型在「自家 harness」裡測試。
結論
而得到的結論很有意思，和之前在 《你現在給 AI 用的 Agent Skills 可能毫無作用，甚至還拖後腿？》 聊過的一結論類似：LLM 自動生成總體的效果“負收益”，人寫的“微弱正收益但不穩定”，並且成本都更高。
這就前面聊過的 Agent Skills 的論文一樣，讓 AI 自己實現 skills 然後在自己持續維護 skills，結果是起不了正向作用，反而還會有負面作用，因為模型不能可靠地“寫出”自己在執行時真正會受益的程序性知識。
對於這個結論，這篇論文說的很直觀：
- LLM 生成的 context files 往往讓成功率更低（平均下降了 3%），同時推高推理成本 20%+
- 開發者寫的 context files 相比 NONE 平均帶來小幅提升（平均 +4% 左右），但也會讓步驟/成本上漲
最有意思的是，他們在實驗裡量化了“更貴”這件事：
- LLM context file 會讓平均 steps 增加
- 成本增加（SWE-Bench Lite 平均約 +20%，AGENTBENCH 平均約 +23% 的量級）
- 開發者文件同樣增加成本
你是不是覺得這個成本也沒什麼？但是從數據可以直觀體現：
- 輸入 Token 增加：例如 Claude Opus 4.6，輸入超過 200K Token 時，計費單價會直接翻倍
- 執行步驟增多：在有上下文文件引導時，智能體傾向於進行更廣泛的探索，平均每項任務多執行 2.45 到 3.92 個步驟
這其實很有意思，因為在很多推廣裡，大家會說 AI 可以維護一切，但是目前的結果看来，AI 在持續維護過程中，如果沒有人的干預，那麼這個偏差值可能隨著時間不斷放大，成本也會不斷增加。
為什麼
那 “為什麼會這樣”？論文的 trace 證據主要體現在：context file 讓 agent 更“謹慎/折騰”，但不更“聰明/精準”，主要可以體現在三個範疇：
- context file 會顯著改變 Agent 行為：產生更多探索、更多測試、更多工具調用，當 context file 存在時：
- agent 更頻繁地跑測試
- grep / read / write 更多（更廣泛地翻倉庫、改文件）
- 更多使用 repo 特定工具（如 uv / repo_tool 等）
而且他們發現：context file 裡寫了某個工具的時候，agent 真的會更常用它，這說明“沒提升”不是因為 agent 不聽話，而更像是“聽話但被加了不必要的工作”。
就像是幻覺反而增多。
- “倉庫 overview” 並沒有讓 agent 更快找到關鍵文件，很多推薦寫法會要求 context file 提供代碼結構概覽，但他們用一個很直觀的指標測「是否更快碰到 PR 真正修改過的文件」：
結果是 有無 context file 並沒讓這件事明顯變快（甚至更慢）。
- 推理 token 明顯上漲，他們用 GPT-5.2 / GPT-5.1 Mini 的「自適應推理 token」現象來佐證「任務變難了」: context file 會讓推理 token 平均上漲一截：
GPT-5.2 的平均推理 Token 增加了 22%，GPT-5.1 Mini 增加了 14% 。
因為 context file（尤其自動生成的）往往加入了“額外流程/要求/檢查點”，agent 又會遵守，因此探索/測試/步驟/推理都上去了，但這些動作並不等價於更高的任務命中率，反而讓任務更容易超時、跑偏或把精力花在無關緊要的規範上。
例外
當然，這裡有一點例外的是：當倉庫文件刪掉，LLM 生成的 context file 反而有用。
其實這也很好理解，對於項目原本文檔很差/缺失的情況，LLM 生成的 md 反而會能補上大量關鍵操作信息（怎麼裝依賴、怎麼跑測試、目錄大概幹嘛），這時候的 AGENTS.md 自然反而體現了作用。
所以反而是越爛的文檔項目越有收益，這就像是 20 分到 70 分，和 70 分到 90 分的區別。
同時，他們還測了更強模型 / 換 meta-prompt：
- 用更強模型（如 GPT-5.2）來生成 context file，不等於更好：在一個數據集上可能漲，在另一個上可能跌，所以並不是一個穩定收益
- 用 Codex 的生成提示詞 vs Claude Code 的生成提示詞，也沒有穩定的輸贏，這體現了現在 AI 還是一個概率預測的本質
所以，問題不在“提示詞不夠好”和“模型不夠好”這種淺層因素，更像是“自動生成這件事本身”還缺少可靠方法。
通過這個，其實我們也可以得到一個啟示：實際上我們日常開發中，使用相對便宜的模型來做文檔工作，確實會是個更有性價比的選擇。
爭議
當然，對於論文的結論：
- 大模型自己維護並生產的
AGENTS.md，在文檔齊全的項目下沒有收益，還增加成本，這個大家都還能夠接受 - 但是對於開發者寫的 context files 相比 NONE 平均帶來 +4% 左右收益這個，在 HN 上大家還是覺得很大爭議
目前 HN 上主要的核心討論點有三個：
AGENTS.md最大價值是 domain knowledge，而開源倉庫很少有這種東西，對於 AI 來說，最有用的是模型無法從 repo 直接推斷的業務/歷史原因/隱含約束，這在閉源大項目常見，但在很多開源（尤其新做的小項目）裡稀缺，所以 benchmark 裡看不到收益。
所以實際上不是
AGENTS.md收益太低，而是大家手寫的太少，並且沒有針對性寫。
- 有人說自己用
CLAUDE.md主要是為了避免蠢錯、減少後續 cleanup/refactor，而不是為了跑分意義上的“performance”，因為論文指標的邊界測的是 exec(test)=PASS 的任務完成率，而不是“代碼質量/可維護性/團隊規範遵守度/後續返工成本”。
但是其實論文也確實測了“成本/步驟”與“行為變化”，並且發現 context file 會讓 agent 更愛跑質量檢查/測試/工具鏈，當然這某種程度上支持了“它可能更謹慎”，問題是這種謹慎在他們的任務裡並未轉化為更高完成率，反而經常只是更高成本。
-
也有人直覺認為：倉庫越大，越需要
AGENTS.md，否則 agent 會浪費很多上下文去找命令、找入口，但論文在“是否更快找到關鍵文件”這個指標上，給出了相反的證據：**overview 並沒有顯著加速觸達關鍵文件，對此他們認為：- overview 的寫法不對：列目錄樹/泛泛描述，信息密度低，不能直接指向“任務常改哪裡”
- benchmark 任務分布的現實差異：SWE-Bench Lite 的熱門倉庫本身文檔/慣例更成熟，agent 已經有“先驗”，而很多人說的“大閉源倉庫痛點”在 benchmark 裡不充分
-
手工寫的 4% 的成功率提升真的是微不足道嗎？不少人認為，如果一個 md 文檔就可以提高 4% 的成功率，這其實已經是一個非常大的收益，當然，4% 的提升並不具備跨模型的一致性，所以這個數據不能看作是一種普適的工程增量。
最後
實際上這篇論文和之前 Skills 那篇都指向同一個觀點：LLM 自動生成總體不穩，常常負收益還更貴，所以更現實的做法是：把自動生成當作“草稿”，但必須由人來重新審閱並修改為更具體和更具針對性的文檔，而 AGENTS.md 最值得寫的內容：
不可從代碼直接推斷、但會導致反復踩坑的東西。
例如 AGENTS.md 可以表述：
- 只能跑
uv而不是pip，以及這麼做的原因 - 必須用某個腳本啟動集成環境，具體哪些 env var
- 關鍵約束（兼容性矩陣、部署目標、性能紅線、安全規則）
另外少寫“目錄導覽”，多寫“任務路由”，更有效的結構往往是：
- 常見任務 ：對應入口文件/模組（例如“新增 API → 先看
api/routes.py+schemas.py”） - 常見 bug 類型 ： 排查路徑（日誌在哪，feature flag 在哪）
更最重要的是，冗長的文檔反而會產生副作用，建議只在 AI 犯錯後才添加針對性的補丁指令，然後支持在子目錄中使用嵌套的 AGENTS.md，實現“按需加載”上下文，避免全局上下文污染，類似於：
之前有人提到的 Claude Code 的上下文壓縮盲區，在上下文過長後的壓縮裡，你給它幾千字符的代碼，壓縮後變成一句話：「用戶提供了代碼」，而這裡的根本原因就是內容太長了，而壓縮是單向的，所以如果是加一行：
[transcript:lines 847-1023]，那麼反而不容易丟失。
另外還有一個小 tip 就是：「不要做 xxx 」的收益其實很一般，在 AI 上更建議使用正面引導或結合 Pre-commit Hooks 進行硬性攔截。
最後，事實上 AI 很多時候是會偷懶和「作弊」的，雖然它會說「我已經讀過並理解了需求」，但實際執行時依然沒有任何約束，這其實就是它直接忽略了 AGENTS.md，因為此時它已經進入了 LLM 的煉丹玄學層面。
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
