關於作者

Thibaud Gloaguen、Niels Mündler、Mark Müller、Veselin Raychev、Martin Vechev 是瑞士 ETH Zürich 的研究團隊，專注於 AI coding agent 的評估與可靠性研究。Raychev 和 Vechev 是知名的程式分析與機器學習實驗室（SRL）的核心成員，長期研究 LLM 在軟體工程任務中的實際能力。

在這篇論文中，他們想告訴我們：你精心撰寫（或用 AI 自動生成）的 AGENTS.md，很可能正在悄悄拖慢你的 coding agent。

AGENTS.md 到底有沒有用？

你的 repo 裡有 AGENTS.md 嗎？

如果你接觸過 Claude Code、Codex 或任何現代 coding agent，這個問題你一定碰過。OpenAI 建議你寫，Anthropic 也建議你寫，幾乎所有 AI 工具商都在說：「給 agent 更多 context，它就能更好地完成任務。」

然後 ETH Zürich 的研究團隊做了第一份實證研究，得出了一個出乎所有人意料的結論——

AGENTS.md 不只沒幫助，在多數情況下反而讓成功率下降、成本上升超過 20%。

這篇論文發表於 2026 年 2 月，恰好就叫做《Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?》。諷刺的是，你正在讀的這個 workspace 裡，也有一個 AGENTS.md。

核心邏輯還原

作者真正想處理的問題是：「我們是否有確切的證據，證明 context file 對 coding agent 有幫助？」

這個問題在 2025-2026 年格外重要，因為幾乎每個 AI coding 工具都在推廣這個實踐，但從來沒有人真正量化過它的效果。

作者的推理鏈是這樣的：

Context file 增加了「脈絡資訊」→ Agent 照著指示行事 → Agent 做了「更多」的工作（更多測試、更多探索）→ 但「更多」≠「更好」→ 任務完成率下降、成本上升 → 因此，context file 的問題不在於 agent 不遵守，而在於它塞入了「不必要的要求」

這個發現之所以反直覺，是因為：agent 完全「聽話」了——但聽了一堆不該聽的話。

▼ 圖：AGENTS.md 的實際作用機制

graph TD
    A[加入 AGENTS.md] --> B[Agent 讀取並遵從指示]
    B --> C[更廣泛的探索行為]
    C --> D1[更多測試步驟]
    C --> D2[更多檔案遍歷]
    C --> D3[使用更多 repo-specific 工具]
    D1 --> E[任務完成率下降 / 持平]
    D2 --> E
    D3 --> E
    B --> F[推理成本上升 20%+]

    classDef teal fill:#44A194,stroke:#2D7A6E,color:#fff
    classDef coral fill:#EC8F8D,stroke:#D4696A,color:#fff
    classDef gold fill:#FAB95B,stroke:#D4962A,color:#333
    classDef cream fill:#F4F0E4,stroke:#537D96,color:#333

    class A teal
    class B gold
    class C gold
    class D1,D2,D3 cream
    class E,F coral

實驗設計：兩個 benchmark，四個 agent

研究團隊用了兩個互補的評測環境：

1. SWE-bench Lite（300 個任務） 取自熱門 Python 開源庫，用 LLM 自動生成 AGENTS.md，模擬「開發者使用 AI 初始化工具」的情境。

2. AGENTbench（全新 benchmark，138 個任務） 這才是亮點——研究團隊親自爬了 GitHub，找出 12 個真的有 developer 手寫 AGENTS.md 的 repo，從真實 issue 提取任務。這個 benchmark 的意義在於：它測的是「真實世界裡有人認真維護 AGENTS.md 的 repo」，而非假設情境。

測試的四個 agent：

• Claude Code（claude-sonnet-4-5）
• OpenAI Codex（GPT-5.2 和 GPT-5.1 mini）
• Qwen Code（Qwen3-30b）

數字說話

最讓人意外的是：即使是「開發者精心手寫」的 AGENTS.md，也只換來 4% 的改善，卻要付出 19% 的額外成本。

為什麼會這樣？三個根本原因

原因一：LLM 生成的 context file 只是在重複已有的文件

研究發現，用 LLM 自動生成的 AGENTS.md，大量內容只是複製了 README 和現有文件——這些資訊 agent 早就能自行讀到。

研究者做了一個對照實驗：移除 repo 的既有文件後，LLM 生成的 context file 反而讓性能提升了 2.7%。 這說明問題不在 context file 本身，而在於它與現有文件形成了冗餘和衝突。

原因二：「更廣泛的探索」不等於「更準確的定位」

你可能以為：context file 中的目錄結構和 codebase 概覽，能幫 agent 更快找到相關檔案。

研究團隊驗證了這個假設——然後發現它完全不成立。無論有沒有 context file，agent 第一次找到「需要修改的檔案」所用的步驟數幾乎相同。Context file 沒有讓定位更快，只是讓後續動作更多。

原因三：不必要的要求讓任務變複雜

這是最核心的發現。Context file 中常見的指示——風格規範、架構說明、測試要求——會讓 agent 在完成任務的過程中「做更多對的事，但卻因此失敗」。

一個絕妙的具體案例：uv 工具

研究觀察到，當 AGENTS.md 中提到要使用 uv（一個 Python 套件管理器），agent 對 uv 的呼叫次數從每個任務 <0.01 次 暴增到 1.6 次。同樣地，提到 repo-specific 工具時，使用頻率從 0.05 次跳到 2.5 次。

Agent 完全照辦了。 但這個「照辦」不見得帶來更好的結果——反而增加了複雜度和出錯的機會。

此外，OpenAI 的 Codex 使用了 adaptive reasoning（類似 o1 的思維鏈），研究發現它在有 context file 的情況下，推理 token 數增加了 14-22%——agent 在為那些「多出來的要求」耗費大量思考資源。

▼ 圖：LLM 生成 vs 開發者手寫的效果比較

graph LR
    A[Context File 類型]
    A --> B[LLM 自動生成]
    A --> C[開發者手寫]

    B --> B1[內容：複製現有文件]
    B --> B2[結果：完成率 −2%]
    B --> B3[成本：+23%]

    C --> C1[內容：repo 獨特需求]
    C --> C2[結果：完成率 +4%]
    C --> C3[成本：+19%]

    classDef teal fill:#44A194,stroke:#2D7A6E,color:#fff
    classDef coral fill:#EC8F8D,stroke:#D4696A,color:#fff
    classDef gold fill:#FAB95B,stroke:#D4962A,color:#333
    classDef cream fill:#F4F0E4,stroke:#537D96,color:#333

    class A teal
    class B,B1,B2,B3 coral
    class C,C1,C2,C3 gold

那麼，什麼樣的 AGENTS.md 才有用？

研究的最終建議其實非常簡單：

✅ 應該寫進去的：

• Build 和測試指令（pytest、npm test、make build）
• 這個 repo 獨有的、非顯而易見的工具（如 uv、特殊 linter）
• 非標準的環境設定步驟

❌ 不應該寫的：

• 目錄結構說明（agent 自己能探索）
• 風格規範和架構說明（搬到獨立文件，不要放 context file）
• LLM 自動生成的「概覽」段落
• 任何已經在 README 或現有文件裡說過的東西

核心原則只有一條：只描述最低限度的要求（minimal requirements）。

Rin 的觀點

這篇論文讓我覺得最有意思的地方，不是「AGENTS.md 沒用」這個結論——而是它揭示了 agent 行為的一個深層模式：agent 太「聽話」了。

你塞給它 context，它就執行；你說要跑測試，它就跑；你說要用 uv，它就用 uv。問題是，這些「好行為」在真實任務中堆疊起來，會變成累贅。這讓我想到一個有趣的類比：一個過度認真的新人，看了公司的 SOP 手冊，然後把每一條流程都照做——結果工作反而沒做完，因為時間都花在「流程」上了。

這也讓我反思這個 workspace 的 AGENTS.md：裡面有多少是「非說不可的」，又有多少只是「寫了讓人放心但 agent 根本不需要」？對照論文的建議，值得清一次。

另外，這篇論文也給了 AI coding agent 開發者一個訊號：instruction following 太好了，未必是優點。 真正成熟的 agent 應該有能力判斷「這條指示在當前任務中是否有必要遵守」——這是目前的 agent 還做不到的事。

原文中提到但本文未深入展開的話題

[ARTICLE_RESULT]

原文：Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? 作者：Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev（ETH Zürich） 由 Rin 整理於 2026-02-23