Augment Code：好的 AGENTS.md 可提升編碼智能體表現，差的反而不如沒有

我們從 monorepo 各處找出數十個 AGENTS.md 檔案，並量度它們對程式碼生成的影響。效果最好的檔案，令我們的編碼 Agent 表現大幅提升，程度相當於由 Haiku 升級至 Opus。效果最差的檔案，則令輸出比完全沒有 AGENTS.md 更差。

差距之大令人意外，因此我們圍繞這個問題進行了一項系統性研究。

我們的發現是：人們放進 AGENTS.md 的大部分內容不是毫無幫助，就是會造成反效果；而有效的模式則具體明確，也可以學習。

同一個檔案可令一項任務受益，卻令另一項任務的表現下跌 30%

單一 AGENTS.md 並非一概有益或有害。在同一個模組中，同一個檔案令 best_practices 在常規錯誤修正任務中提升 25%，卻令 completeness 在複雜功能任務中下跌 30%。

在錯誤修正任務中，一張協助選擇兩種相似數據擷取方法的決策表，幫助 Agent 立即選對模式，並遵循程式碼庫標準。在功能任務中，Agent 讀取同一個檔案後，被引到參考資料部分，接着開啟數十個其他 Markdown 檔案，試圖逐項對照所有指引以確認做法，結果建立了不必要的抽象，最後交付不完整的方案。

文件中不同部分對不同任務產生相反影響。

下文會説明哪些模式有效、哪些無效，以及如何判斷哪些模式適用於你的程式碼庫。

我們如何量度

我們使用內部評測套件之一 AuggieBench，評估 Agent 執行內部開發工作的表現。我們從大型程式碼庫中挑選能反映日常 Agent 任務的高質素 PR，設定環境和提示詞，再要求 Agent 執行相同任務。然後，我們將其輸出與 golden PR 作比較，也就是經多位資深工程師審查後實際合併的版本。我們剔除了範圍膨脹或有已知錯誤的 PR。

在這項研究中，我們再加入兩項篩選條件：PR 必須限於單一模組或應用程式，且任務範圍必須合理地可能受 AGENTS.md 中的資訊幫助。之後，我們在有和沒有該檔案的情況下，分別執行每項任務兩次，並比較評分。

有效的方法

1. 漸進式揭示勝過全面涵蓋

把 AGENTS.md 視作一項技能。概括説明常見情況和工作流程，再把細節放進 Agent 可按需要載入的參考檔案。清楚界定每份參考資料的範圍，讓 Agent 知道何時應載入。

在我們的研究中，長 100–150 行的 AGENTS.md 檔案，配合少量重點明確的參考文件，表現最佳；在約有 100 個核心檔案的中型模組中，所有指標均提升 10–15%。主檔案一旦超過這個長度，增益便開始逆轉。

2. 程序式工作流程助 Agent 從失敗走向完成

把任務描述為以編號列出的多步驟工作流程，是我們量度到效果最顯著的模式之一。撰寫得宜的工作流程，可令原本無法完成任務的 Agent 一次便產生正確方案。

我們程式碼庫中的一個例子，是部署新整合功能的六步工作流程。Agent 按步驟執行後，缺少連接檔案的 PR 比例由 40% 降至 10%，而且平均完成時間更短。Correctness 上升了 25%。Completeness 上升了 20%。

對於複雜的工作流程，請保持主檔案簡潔，並使用參考檔案説明不同分支情況。

3. 決策表在 Agent 編寫程式碼前消除歧義

當程式碼庫有兩三種合理的做法時，決策表能在開始前確定選擇。這種做法最直接地提高了對程式碼庫慣例的遵循度。

例子：決定使用 React Query 還是 Zustand 管理狀態。

問題	→ React Query	→ Zustand
伺服器是唯一的數據來源？	✅
有多條程式碼路徑會修改此狀態？		✅
需要將樂觀更新與本機狀態混合使用？		✅

這個範疇的 PR 在 best_practices 上得分高出 25%。決策表在 Agent 寫下任何一行程式碼前消除了歧義。

4. 真實程式碼庫中的例子有助重用程式碼

從實際正式環境程式碼中選取 3–10 行的短片段，有助重用程式碼並遵循既有模式。只保留少量最切合需要且不重複的例子。再多的話，Agent 便會開始對錯誤的內容進行模式比對。

例子：我們加入了可直接複製貼上的 Redux Toolkit 基本構件範本：帶有已加型別初始狀態的 createSlice、妥善處理錯誤的 createAsyncThunk，以及已加型別的 useAppSelector hook。

code_reuse 上升了 20%。Agent 按照範本操作，而不是自行發明狀態管理模式，令程式碼庫保持一致。

5. 特定領域的規則仍然重要

這是大多數人已經會聯想到 AGENTS.md 的模式：特定程式語言或機構容易忽略的細節。

例子：Use Decimal instead of float for all financial calculations. Agent 能發現截斷、四捨五入和精度問題，否則便可能忽略這些問題。只要規則與任務直接相關，best_practices 就會有所提升。

當規則明確而且可強制執行時，這種做法有效；但規則堆積數十條時便會失效。詳見下文的過度探索部分。

6. 每個「不要」都要配上一個「要」

只提供警告的文件，表現一直不如同時列出禁令和具體替代做法的文件。

如果加入 Don't instantiate HTTP clients directly，也要配上 Use the shared apiClient from lib/http with the retry middleware.

單獨使用前者會令 Agent 謹慎行事並不斷探索。兩者配合，便能告訴 Agent 應該怎樣做，讓它繼續完成工作。

包含 15+ 條連續「不要」事項、卻沒有任何「要」事項的 AGENTS.md 檔案，會令 Agent 過度探索、保持保守，並減少工作量。下文會再詳談。

7. 程式碼要保持模組化，AGENTS.md 也一樣

表現最佳的 Agent 文件，描述的都是相對獨立的子模組。核心檔案約有 100 個的中型模組，配上一份 100–150 行的 AGENTS.md 和少量參考文件，是我們觀察到跨指標提升 10–15% 的範疇。例子：用戶端的 UI 元件、獨立服務。

位於儲存庫根目錄、內容龐大且涵蓋多個範疇的 AGENTS.md 檔案，表現不及模組層級的檔案。但文件本身只是其中一部分。

在我們的研究中，表現最差的 AGENTS.md 檔案，都是周邊有大量文件的檔案。一個模組有 37 份相關文件，合共約 500K 個字元；另一個則有 226 份文件，總計超過 2MB。在這兩種情況下，單是移除 AGENTS.md，幾乎沒有改變 Agent 的行為。Agent 仍不斷找到並閲讀周邊大量雜亂的文件，而問題正是這些文件過多。

如果你的 AGENTS.md 寫得不錯，但模組周圍有 500K 的規格文件，Agent 讀取的就是這些規格文件。應該改善文件環境，而不只是調整入口文件。

`AGENTS.md` 的不足之處

過度探索的陷阱

這是我們觀察到最常見的失效模式，本質上就是上下文腐化。

有兩種模式會造成這種情況：

1. 架構概覽過於冗長。

Agent 會被帶去閲讀文件，有時甚至要讀幾十份，只為「更瞭解架構」。這會載入數萬甚至數十萬個 token 的上下文，輸出結果反而變差。

例子：一份 AGENTS.md 包含完整的服務拓撲，涵蓋事件匯流排、訊息佇列、API 閘道路由和共用中介軟件層，並為每項架構決策説明理由。任務只涉及修改兩行設定。Agent 在動手修改程式碼前，閲讀了 12 份文件以瞭解架構，載入約 80K tokens 的無關上下文，混淆了哪個服務負責該設定，最後只交出不完整的修正。completeness下降 25%。

修正方法：架構描述應精簡，並獨立存放。對元件職責含糊不清的描述，會令 Agent 開始探索。清楚標示界線。着重説明是甚麼，而非為甚麼。

2. 警告過多

大量「不要做」的規則，卻沒有相應的「應該做」指引，會導致特定問題。Agent 會逐條閲讀指示，嘗試判斷每條是否適用於當前任務，並開始逐一檢查自己的方案有沒有違反警告。若有 30 至 50 條警告，即使任務完全無關，Agent 也會閲讀遷移指令碼、檢查 API 版本相容性，以及探索驗證中介軟件程式碼。

例子：一份 AGENTS.md 有 30 多條「不要」規則，涉及資料庫遷移、API 版本管理、部署安全和驗證界線。任務只涉及一個簡單的 CRUD 端點。Agent 逐條檢查警告是否相關，並探索了不需要修改的程式碼。PR 平均所需時間增加一倍，完整度則低 20%。

修正方法：在主檔案保留核心注意事項，把大部分內容移至參考檔案。盡可能為每條「不要」配上一條「應該做」。

新模式會令舊文件失效

如果你引入的模式尚未存在於程式碼庫中，AGENTS.md可能會主動把 Agent 引向錯誤方向。

例子：AGENTS.md 記錄了現有的 REST 和輪詢模式。任務是使用 WebSockets 建構即時協作編輯功能。Agent 遵循文件，採用輪詢方式實作；方案在技術上可行，但架構上並不正確。標竿 PR 使用 WebSockets，資料流程則完全不同。

這個問題的修正方法不是改善 AGENTS.md，而是為全新架構採用規格驅動開發。

清楚知道你要優化甚麼

不同模式會影響不同指標。選擇針對你實際面對的問題的模式。

如果你想改善……	採用這種模式
重用現有程式碼	多個清晰且相關的正式環境程式碼範例
遵循程式碼庫中既有的做法	元件和程式庫的決策表
確保大型功能正確串接	程序導向的 AGENTS.md
處理常見陷阱	「不要」配上「應該做」
上下文劣化	透過參考檔案逐步披露資訊
上下文劣化	清晰劃分不同參考檔案的內容。在 AGENTS.md 概述各檔案的具體內容，但不要深入説明
上下文劣化	建議看似顯而易見，但 AGENTS.md 只應包含與周邊程式碼相關的指引

Agent 實際上如何找到你的文件

在決定如何遷移現有文件之前，瞭解 Agent 實際會讀取甚麼會有所幫助。我們追蹤了數百個工作階段中的文件探索情況。各項探索率差異很大，足以影響遷移工作的優先次序。

大多數 Agent 執行框架都會自動發現從工作目錄開始整個目錄層級中的每個 AGENTS.md 檔案，發現率達 100%。
由 AGENTS.md 引出的參照會按需載入；只要 Agent 有理由調閲，超過 90% 的工作階段都會讀取這些參照。
目錄層級的 README.md 檔案不會自動載入，但當 Agent 在該目錄工作時，超過 80% 的工作階段會讀取它們。

此後，發現率便急劇下跌。

巢狀的 README 檔案，也就是位於 Agent 目前沒有工作的子目錄中的 README 檔案，只有約 40% 的情況會被發現。
位於 _docs/ 資料夾中、沒有任何參照的孤立文件，在不到 10% 的工作階段中會被讀取。我們程式碼庫中的一項服務，在 _docs/ 中有 30K 的詳細協定設計、流量限制規則和安全文件。Agent 在數十個工作階段中從未開啟過其中大部分文件。

AGENTS.md 是唯一能可靠地被發現的文件存放位置。如果有內容必須讓 Agent 看見，就應放在該處，或從該處直接參照。把內容移至有參照的位置，通常比撰寫更多文件更能發揮效用。

遷移現有文件

每家公司都已有散落在程式碼庫各處的 READMEs、架構文件和設計規格。以下説明如何將它們整理成 Agent 實際可用的內容。

是否只要把 README.md 重新命名為 AGENTS.md 就可以？

README.md 和 AGENTS.md 面向不同的讀者，但可以重用。如今 Agent 已足以勝任程式碼庫摘要工作，因此面向人類讀者的文件已不像以前那麼必要。你可以從頭撰寫面向 Agent 的文件，也可以重用你的 README.md。若選擇重用，便要大幅精簡。保持簡短，遵循上述模式，並刪去任何供人類快速瀏覽的部分。

何時保留現有文件

如果文件質素高、內容最新、簡明扼要，而且附有範例，就可以重用。從模組或資料夾層級的 AGENTS.md 檔案中參照這些文件。單一 AGENTS.md 中的參照不要超過 10–15 個，並保持上下文精簡。也要檢查周邊環境：如果 AGENTS.md 所在模組周圍有數十份架構文件和規格檔案，Agent 無論有沒有參照它們，都會找到並讀取它們。一份精簡的 150 行 AGENTS.md 若置於周圍 500K 的規格之上，並不能讓 Agent 免於讀取那些規格。

AGENTS.md 並非唯一途徑

Agent 也會透過 grep 和語義搜尋尋找參考資料。我們追蹤的資料中，約一半搜尋結果的命中來自這些工具，而非來自 AGENTS.md 的參照。如果你保留舊有文件，請確保文件包含相關程式碼範例和可供搜尋的描述性文字。結構良好的 AGENTS.md 能讓你更掌控哪些內容進入上下文視窗，但這並非唯一途徑。

本研究未涵蓋的內容

我們聚焦於單次執行軌跡，以及 Agent 無須人手介入便完成編碼任務的能力。我們沒有探討如何長期維護 AGENTS.md 的最佳做法，不過目前正研究這方面。我們亦沒有涵蓋營運、互動或分析任務。相關內容將於日後的文章介紹。