新研究重新評估 AGENTS.md 文件在 AI 編碼中的價值

作者 | Bruno Couriol

譯者 | 劉雅夢

盡管業(yè)界普遍推薦，但蘇黎世聯邦理工學院（ETH Zurich）的一篇新論文得出結論，AGENTS.md文件可能經常阻礙 AI 編碼智能體。研究人員建議完全省略由 LLM 生成的上下文文件，并限制人類編寫的指令只包含不可推斷的細節(jié)，例如非常具體的工具或自定義構建命令。

團隊（Thibaud Gloaguen、Niels Mündler、Mark Müller、Veselin Raychev、Martin Vechev）通過指出盡管目前有 60,000 個開源倉庫包含 AGENTS.md 等上下文文件，并且許多智能體框架都內置了自動生成這些文件的命令，但還沒有進行嚴格的實證研究來調查這些文件是否真的提高了 AI 智能體解決現實世界編碼任務的能力，從而為研究提供了理由。

研究人員（其中一位為 Humanity Last Exam 基準測試做出了貢獻）構建了 AGENTbench，這是一個新的數據集，包含 138 個來自小眾倉庫的真實世界 Python 任務。這種設置故意避免了像 SWE-bench 這樣的流行基準測試的偏見，AI 模型可能已經部分記住了這些測試。團隊在三個不同場景下測試了四個智能體（Claude 3.5 Sonnet、Codex GPT-5.2 和 GPT-5.1 mini 以及 Qwen Code）：不使用上下文文件、使用 LLM 生成的文件和人類編寫的文件。研究人員通過跟蹤三個智能體指標來評估倉庫級指令的實際影響：任務成功率（由倉庫單元測試確定）、代理步驟數量和總體推理成本。所有選定的小眾倉庫都包含人類編寫的上下文文件；前兩個場景通過移除或替換這些文件進行測試。

研究人員發(fā)現，LLM 生成的上下文文件會降低性能，與不提供任何上下文文件相比，任務成功率平均降低了 3%。它們還一致增加了智能體采取的步驟數量，將推理成本提高了 20% 以上。

另一方面，人類編寫的文件確實提供了邊際收益，在 AGENTbench 上任務成功率平均提高了 4%。然而，這種正面增長與步驟數量的并行增長形成對比，成本也增加了高達 19%。

在 AGENTS.md 文件中包含諸如架構概覽或倉庫結構解釋等信息似乎并沒有減少模型為手頭任務定位相關文件所花費的時間。

為了理解性能下降和成本增加的原因，作者對智能體的工具調用和推理模式進行了深入的跟蹤分析。智能體通常遵循 AGENTS.md 文件中包含的指令。結果，它們運行了更多的測試，讀取了更多的文件，執(zhí)行了更多的 grep 搜索，并進行了更多的代碼質量檢查。雖然這種行為非常徹底，但通常對于解決手頭的具體任務來說是不必要的。數據表明，額外的上下文迫使推理模型“思考”得更努力，而沒有產生更好的最終補丁。

作者最后強調了研究結果與當前向使用 AI 代碼智能體的開發(fā)人員提出的建議之間的差距：

我們發(fā)現所有上下文文件都一致地增加了完成任務所需的步驟數量。LLM 生成的上下文文件對任務成功率有邊際的負面影響，而開發(fā)人員編寫的文件則提供了邊際的性能提升。 我們的跟蹤分析顯示，上下文文件中的指令通常被遵循，并導致更多的測試和更廣泛的探索；然而，它們并不作為有效的倉庫概覽。總體而言，我們的結果表明上下文文件對智能體行為只有邊際影響，并且可能只有在手動編寫時才受歡迎。這突出了當前智能體 - 開發(fā)人員建議與觀察結果之間的具體差距，并激發(fā)了未來工作，即以有原則的方式自動生成簡潔、與任務相關的指導，以供編碼智能體使用。

開發(fā)人員對這項研究表示了興趣。一位開發(fā)人員指出，這項研究實際上應該讓開發(fā)人員專注于編寫有用的 AGENTS.md 文件：

我讀了這項研究。我認為它實際上與作者建議的相反——實際上是在支持好的 AGENTS.md 文件。 [...] AGENTS.md 文件的最大用例是模型不知道且無法立即從項目中推斷出的領域知識。這是從看到智能體因這種缺陷而掙扎中慢慢獲得的。這在閉源中非常常見，但在擁有 AGENTS.md 文件的公共 GitHub 項目中非常罕見——絕大多數是最近以 LLMs 中心的小型氛圍編程項目。如果在后一種項目上看到了 4% 的增長，這些項目本來就有非常混雜質量較差的 AGENTS.md 文件，那么對于擁有高質量 AGENTS.md 的大型項目來說，它們在與智能體合作時是無價的。

另一位開發(fā)人員指出，上下文文件可能對開發(fā)人員比對 AI 利用具更有用：

我已經維護一個 CLAUDE.md 文件大約 3 個月了，它橫跨兩個項目，改進是明顯的，但不是你所期望的原因。它提供的實際 token 級上下文并不重要，重要的是，編寫它可以迫使你表達關于你的代碼庫的事情，這些之前只是在你的腦海中。像“我們因為 Y 中的遺留約束而對 X 使用這種奇怪的模式”之類的東西。一旦寫下來，智能體就會把它撿起來，但團隊中的每個新成員也會這樣做。

開發(fā)者可以 在線審閱論文。像AGENTS.md、CLAUDE.md或.cursorrules這樣的上下文文件的使用，在 2025 年下半年變得日益重要，這與 AI 編碼智能體提供商的更大推動相吻合。

https://www.infoq.com/news/2026/03/agents-context-file-value-review/

聲明：本文為 InfoQ 翻譯，未經許可禁止轉載。