# 策展 · X (Twitter) 🔥🔥

> 作者：Augment Code (@augmentcode) · 平台：X (Twitter) · 日期：2026-04-24

> 原始來源：https://x.com/augmentcode/status/2047164534310494709

## 中文摘要

# 一份好的 AGENTS.md 等同於模型升級。一份糟糕的 AGENTS.md 比沒有文件還糟糕。

我們從 monorepo 中提取了數十個 AGENTS.md 檔案，並測量了它們對程式碼生成的影響。表現最好的檔案讓我們的程式撰寫 Agent 獲得了品質上的飛躍，相當於從 Haiku 升級到 Opus。而表現最差的檔案則讓輸出結果比完全沒有 AGENTS.md 時更糟。

這種差距大到讓我們感到驚訝，因此我們圍繞此現象進行了一項系統性的研究。

我們發現：人們放入 AGENTS.md 中的大多數內容，要麼毫無幫助，要麼反而有害；而真正有效的模式其實非常具體且可學習。

## 同一個檔案對某個任務可能有幫助，對另一個任務卻會導致 30% 的效能下降

單一的 AGENTS.md 並非絕對的好或壞。同一個檔案在處理常規 Bug 修復時，能將最佳實踐 (best_practices) 提升 25%，但在同一個模組處理複雜功能任務時，卻會導致完整性 (completeness) 下降 30%。

在 Bug 修復任務中，一個用於在兩種相似資料獲取方式之間進行選擇的決策表，能幫助 Agent 立即選出正確的模式，並保持在程式庫標準之內。但在功能任務中，Agent 讀取了同一個檔案後，卻被引導至參考區段，開啟了數十個其他 Markdown 檔案，試圖根據每一條準則來驗證其方案，結果創造了不必要的抽象層，最後交付了一個不完整的解決方案。

文件的不同區塊對不同任務產生了截然相反的效果。

接下來將說明哪些模式有效、哪些會失敗，以及如何判斷你的程式庫適合哪種模式。

## 我們是如何測量的

我們使用內部評測套件之一的 AuggieBench，來評估 Agent 執行內部開發工作的表現。我們從大型儲存庫中挑選高品質的 PR，這些 PR 反映了日常的 Agent 任務，設定好環境與 Prompt，並要求 Agent 執行相同的任務。接著，我們將其輸出結果與「黃金 PR」（即經過多位資深工程師審查後實際合併的版本）進行比較。我們過濾掉了那些範圍蔓延 (scope creep) 或已知有 Bug 的 PR。

針對這項研究，我們增加了兩個篩選條件：PR 必須包含在單一模組或應用程式內，且其範圍必須是 AGENTS.md 中的資訊可能產生幫助的領域。隨後，我們對每個任務執行兩次測試（分別在有與沒有該檔案的情況下），並比較分數。

## 什麼是有效的

1. 漸進式揭露 (Progressive disclosure) 勝過全面覆蓋

將你的 AGENTS.md 視為一項技能。以高層級概括常見案例與工作流程，然後將細節推送到 Agent 可按需載入的參考文件中。保持每個參考文件的範圍清晰，這樣 Agent 才知道何時該呼叫它。

在我們的研究中，長度在 100–150 行且包含少量重點參考文件的 AGENTS.md 表現最佳，在約 100 個核心檔案的中型模組中，所有指標均提升了 10–15%。一旦主檔案超過這個長度，收益便開始遞減。

2. 程序化工作流程能讓 Agent 從失敗走向完成

將任務描述為編號的多步驟工作流程，是我們測量過最強大的模式之一。一份編寫良好的工作流程，可以讓 Agent 從「無法完成任務」轉變為「一次就產出正確解決方案」。

我們程式庫中的一個例子：部署新整合的六步驟工作流程。Agent 逐步執行了該流程。缺失組態檔案 (wiring files) 的 PR 比例從 40% 降至 10%，且 Agent 平均完成速度更快。正確性提升了 25%，完整性提升了 20%。

對於複雜的工作流程，請保持主檔案簡潔，並使用參考文件來處理分支案例。

3. 決策表在 Agent 撰寫程式碼前解決歧義

當你的程式庫有兩種或三種合理的方式來執行某件事時，決策表能強制 Agent 在一開始就做出選擇。這是最直接改善 Agent 遵循程式庫規範的模式。

範例：解決 React Query 與 Zustand 在狀態管理上的選擇問題。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636156-iaHGj7wifb0AAkGKdjpg.jpg)

該領域的 PR 在最佳實踐指標上得分高出 25%。該表格在 Agent 寫下任何一行程式碼之前，就解決了歧義。

4. 來自真實程式庫的範例能改善程式碼重用

從實際生產環境程式碼中擷取 3–10 行的簡短片段，能改善重用性與模式遵循度。請將範例限制在最相關且不重複的幾個即可。超過這個數量，Agent 就會開始在錯誤的地方進行模式匹配。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636227-iaHGj86OCaoAAEbh7jpg.jpg)

5. 領域特定規則依然重要

這是大多數人已經與 AGENTS.md 連結在一起的模式：特定語言或組織的潛規則 (gotchas)。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636140-diaHGj9AI1aMAAvTsjpg.jpg)

當規則明確且可執行時，這很有效。但當你堆疊數十條規則時，它就失效了。請參閱下方的「過度探索」章節。

6. 將每個「不要」與一個「要做」配對

僅有警告的文件，其表現始終不如將禁止事項與具體替代方案配對的文件。

如果你加上「不要直接實例化 HTTP 客戶端」，請同時配對「請使用 lib/http 中帶有重試中介軟體的共用 apiClient」。

單獨寫前者會讓 Agent 變得謹慎且傾向過度探索。兩者配對則告訴它該怎麼做，然後繼續執行。

包含 15 個以上連續「不要」且沒有「要做」的 AGENTS.md，會導致 Agent 過度探索、保持保守，並減少實際工作量。詳情見下文。

7. 保持你的程式碼模組化，AGENTS.md 也要

表現最好的 Agent 文件描述的是相對獨立的子模組。在中型模組（約 100 個核心檔案）中，搭配 100–150 行的 AGENTS.md 和少量參考文件，我們看到了 10–15% 的跨指標增長。範例：客戶端的 UI 元件、獨立服務。

位於儲存庫根目錄、龐大且跨領域的 AGENTS.md 表現不如模組層級的文件。但文件本身只是故事的一部分。

在我們的研究中，表現最差的 AGENTS.md 是那些堆疊在大量周邊文件之上的檔案。有一個模組擁有 37 個相關文件，總計約 50 萬字元。另一個模組有 226 個文件，總計超過 2MB。在這兩種情況下，僅僅移除 AGENTS.md 對 Agent 的行為幾乎沒有影響。Agent 持續尋找並讀取周邊散亂的文件，而這些散亂的文件才是問題所在。

如果你的 AGENTS.md 寫得很好，但你的模組周圍有 50 萬字元的規格說明，Agent 讀取的其實是那些規格說明。請修復文件環境，而不僅僅是入口點。

## AGENTS.md 的不足之處

過度探索的陷阱

這是我們觀察到最常見的失敗模式，本質上就是 context 腐敗。

兩個模式會導致此問題：

1. 過多的架構概覽。

Agent 被吸引去閱讀文件檔案（有時多達數十個），試圖「更深入了解架構」。它載入了數十萬個 token 的 context，結果輸出品質反而下降。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636194-iaHGj8QpWakAAl59Gjpg.jpg)

2. 過多的警告

一大段沒有對應「要做」的「不要」清單會產生特定的失敗。Agent 讀取每一條指令，試圖弄清楚它是否適用於當前任務，並開始根據每一條警告來驗證其解決方案。若有 30–50 條警告，這意味著它會去讀取遷移腳本、檢查 API 版本相容性，並探索驗證中介軟體程式碼，即使在一個完全不需要這些資訊的任務中也是如此。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636166-iaHGj8ZAHb0AAU2ULjpg.jpg)

新模式會破壞舊文件

如果你引入了一個在你的程式庫中尚不存在的模式，AGENTS.md 可能會主動將 Agent 導向錯誤的方向。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636174-iaHGj8fFLboAAMpBnjpg.jpg)

## 了解你的優化目標

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

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1776991636222-iaHGj8lF7aEAAPr1rjpg.jpg)

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

在決定如何遷移現有文件之前，了解 Agent 實際上讀取什麼很有幫助。我們追蹤了數百個對話階段中的文件發現過程。發現率的不平衡足以影響遷移的優先順序。

- AGENTS.md 檔案在 100% 的情況下會被自動發現，對於大多數 harness 而言，它會從工作目錄層級結構中的每個檔案進行搜尋。

- 當 Agent 有理由呼叫時，AGENTS.md 中的參考連結會在超過 90% 的對話階段中被按需載入並讀取。

- 目錄層級的 README.md 檔案不會被自動載入，但當 Agent 在該目錄下工作時，它會在 80% 以上的對話階段中讀取它們。

在此之後，發現率會急劇下降。

- 巢狀 README（即 Agent 當前未在其中工作的子目錄中的 README 檔案）只有約 40% 的機率會被發現。

- 位於 `_docs/` 資料夾中且沒有任何連結指向的孤立文件，在不到 10% 的對話階段中會被讀取。我們程式庫中的一個服務在 `_docs/` 中有 3 萬字詳細的協定設計、節流規則與安全文件。在數十個對話階段中，Agent 從未開啟過其中大部分文件。

AGENTS.md 是唯一具有可靠發現機制的文件位置。如果某件事需要被看見，它要麼放在那裡，要麼直接從那裡被引用。將內容移動到被引用的位置，通常比撰寫更多文件更具槓桿效應。

## 遷移現有文件

每家公司在儲存庫中都散佈著 README、架構文件與設計規格。以下是如何將這些內容轉化為 Agent 真正能使用的東西。

你應該直接把 README.md 改名為 AGENTS.md 嗎？

README 與 AGENTS.md 服務的對象不同，但它們可以被重用。現在 Agent 在總結程式庫方面的能力已經足夠強，以至於面向人類的文件不再像過去那麼必要。你可以從零開始編寫一份 Agent 專用文件，或者重用你的 README。如果重用，請進行激進的刪減。保持簡短，遵循上述模式，並刪除任何為了讓人類快速瀏覽而存在的區段。

何時該保留現有文件

如果文件品質高、時效性強、切中要點且包含範例，請重用它們。從模組或資料夾層級的 AGENTS.md 檔案中引用它們。不要在單一 AGENTS.md 中放入超過 10–15 個參考連結，並保持 context 簡潔。同時審查周邊環境：如果你的 AGENTS.md 周圍的模組有數十個架構文件與規格檔案，無論你是否引用它們，Agent 都會找到並讀取它們。一份放在 50 萬字元周邊規格之上的 150 行精簡 AGENTS.md，無法將 Agent 從那些規格中拯救出來。

AGENTS.md 並非唯一途徑

Agent 也透過 grep 和語意搜尋來尋找參考資料。在我們的追蹤中，大約一半的搜尋結果命中來自這些工具，而不是來自 AGENTS.md 的參考連結。如果你保留了舊版文件，請確保這些文件包含相關的程式碼範例與可搜尋的描述性文字。結構良好的 AGENTS.md 讓你對進入 context window 的內容有更多控制權，但它並非唯一的入口。

本研究未涵蓋的內容

我們專注於一次性 (one-shot) 的軌跡以及 Agent 在沒有人類干預下完成程式撰寫任務的能力。我們沒有研究長期維護 AGENTS.md 的最佳實踐，儘管我們目前正在探索這一點。我們也沒有涵蓋操作、互動或分析任務。這些內容將在未來的文章中討論。

作者：Slava Zhenylenko (技術人員)

## 標籤

Agent, 教學資源, Skills, Anthropic, Claude