前面三個階段，從不同角度處理了 AI 時代的軟體工程問題：

• Control：implementation 不可信，所以建立 tests、lint、type checker、CI 與文件。
• Contain：系統無法一次被完整理解，所以建立 boundary 與 contract，限制一次 change 需要理解與影響的範圍。
• Choose：未來的需求無法預測，所以要根據證據，決定什麼設計值得提前付出成本。

這些機制現在都已經在 repo 裡了。但把任務交給 coding agent 時，還有一個問題：agent 應該在開始工作前，就知道哪些事？ 這正是 AGENTS.md 要處理的問題。

AGENTS.md：repo 裡的另一種 context

coding agent 和一般的聊天模型不同。它不只產生 code，還能搜尋 repo、讀檔案、執行命令、修改 code，再根據測試結果繼續工作。也就是說，agent 有能力自己取得 repo 裡的資訊。

但能取得，不代表它會在對的時候找到、理解並使用。一個 repo 可能已經有：

• pyproject.toml：定義開發工具。
• tests 與 CI：定義可以執行的檢查。
• README 與其他 docs：說明專案的現況。
• ADR：記錄過去的設計決策。

這些資訊本來就在。問題是 agent 接到任務時，不一定知道哪些對這次工作重要。

AGENTS.md [3] 讓 repo 可以預先告訴 coding agent 一些工作規則。它就是 Markdown，沒有特殊語法，也可以在不同目錄各放一份。支援它的 coding agent 會依各自的載入機制，把內容提供給模型。

要注意的是，AGENTS.md 不一定放在 system prompt 裡；它以什麼角色載入、什麼時候被讀、優先順序如何，都取決於 agent 的實作。真正重要的是：AGENTS.md 的內容會在任務開始前，就成為 agent 的工作 context。

這也是它的代價。每多寫一條規則，agent 就多一項要理解、判斷、遵守的要求。那麼，給更多 context，真的會讓 agent 做得更好嗎？

規則更多，結果不一定更好

2026 年有一篇研究 [1] 直接測了這件事。研究者用 SWE-bench Lite 與自己建立的 CTXbench，在 Claude Code、Codex、Qwen Code 與不同的模型上，比較三種情況：

1. None：沒有 context file。
2. LLM：模型自動產生的 context file。
3. Dev：開發者維護的 context file，這一組只在 CTXbench 上進行。

結果很反直覺。

• 自動產生的：成功率在 SWE-bench Lite 平均下降約 0.5 個百分點，在 CTXbench 下降約 2.0 個百分點。差異未達統計顯著，不能據此說 AGENTS.md 一定會降低成功率；但成本分別增加了約 20% 與 23%。
• 開發者維護的：表現比自動產生的好，在 CTXbench 上比沒有 context file 高約 2.4 個百分點，但同樣未達統計顯著。

研究者也發現一件確定的事：agent 真的會照 context file 裡寫的做。 context file 提到某個工具（例如 uv）時，agent 使用它的頻率明顯增加；有 context file 時，agent 也更常搜尋檔案、讀 code、跑測試。

所以問題不完全是 agent 不聽話，反而可能是：agent 遵守了更多規則、做了更多事，但這些額外的工作沒有讓任務更容易成功。 研究還發現，repo 導覽並沒有明顯幫助 agent 更快找到該修改的 code。

這是一個重要的提醒：提供資訊，和改善成果，是兩件事。

要注意的是，這篇研究主要評估 Python repo 裡的任務，不能直接推論到所有專案、語言與任務；它也沒有證明 AGENTS.md 越短越好。但至少可以確定，不能再假設「放越多專案知識進 AGENTS.md，agent 就做得越好」。

AGENTS.md 的本質：決定哪些資訊值得預先提供

到這裡可以重新理解 AGENTS.md。它不是第二份 README，也不是把整個 repo 的知識濃縮成一份 Markdown。我更傾向把它看成一個 context management 的工程決策：repo 裡的資訊很多，但不是每一項都需要在任務開始前進到 agent 的 context。

資訊可以分成兩種。

第一種，agent 可以等到需要時再讀。例如某個 function 的 implementation、module 的完整 API、某個設計決策的詳細理由。這些留在 code、docs 或 ADR 裡，agent 需要時再去查。

第二種，我們希望 agent 開始工作前就知道。例如非標準的開發流程、重要的相容性限制，或是容易被忽略、卻不能隨意破壞的既有約定。

第二種資訊不一定無法從 repo 找到。差別在於：我們願不願意承擔 agent 沒有主動找到它的風險？

但預先放進 AGENTS.md 並不是免費的。即使只是文字，也會增加 context 用量、推理成本，以及 agent 要遵守的要求。所以決定一條規則值不值得放，我至少會問四個問題：

1. 重要嗎？ agent 忽略它，會不會造成有代價的錯誤？
2. 容易取得嗎？ agent 能不能可靠地從既有的 code、設定檔或 docs 得到同樣的資訊？
3. 經常適用嗎？ 它是多種任務都要知道的規則，還是只有某一種工作才用得到？
4. 能改變什麼具體行為？ agent 知道之後，該做什麼，或該避免什麼錯誤？

這四個問題不是論文提出的最佳公式，而是我根據研究結果整理出的判斷方式。重點不是每一題都要答「是」，而是讓每一條規則都有留下來的理由。

其中最容易被忽略的是最後一個問題。像「Write clean code」這種要求，agent 讀完並不知道何時適用、該做什麼、怎麼確認做對。這種模糊的要求，不值得寫進 AGENTS.md。

回到三個階段：哪些知識值得提前交代

接著把前面三個階段拿出來檢查。

Control：怎麼正確工作與驗證

這個階段的內容最容易轉成 AGENTS.md。前面介紹過 Git、formatter、linter、type checker、tests、CI 與 docs，它們的目的是讓 change 可以被檢查、驗證與修正。

值得放進 AGENTS.md 的不是這些工具的完整介紹，而是這個專案特有的用法：

• 正確的開發環境與套件管理器。
• 執行相關 tests、lint、type check 的方式。
• 哪些類型的變更需要更新哪些文件。
• 完成任務前要跑哪些檢查。

像 uv 這種工具，即使能從 repo 的設定檔看出來，如果 agent 經常用錯，仍然值得明確指定。重點不是查不查得到，而是 agent 能不能可靠地用對。

但也要記得，AGENTS.md 只是提供規則。它不能保證 agent 一定會跑測試，更不能保證產出的 code 是對的。真正需要強制的限制，還是要交給 CI、tests 與其他可執行的檢查。

Contain：哪些 boundary 不該跨越

階段二談的是建立 boundary，讓理解與修改的影響範圍保持局部。這個階段不像 Control 有那麼明確、可以直接列出來的內容，因為 AGENTS.md 必須和程式碼一起合作，大致分成兩步。

1. 程式碼先提供明確的 boundary

repository/
├── AGENTS.md
├── contract/
├── backend/
│   └── src/
├── frontend/
│   └── src/
└── infrastructure/

2. AGENTS.md 再補上從結構看不出來的規則

- frontend 與 backend 之間溝通的 schema，一律定義在 `contract/`。
- frontend 與 backend 不直接 import 對方的 code，只能依賴 `contract/`。

目錄結構 agent 自己看得到，但「schema 只能放這裡」「兩邊不能互相 import」這類意圖，從結構看不出來，這才是值得寫進 AGENTS.md 的部分。專案已經明確建立的其他 dependency 限制，也是同樣的道理。

但這不代表要把整份架構文件搬進去。架構的完整說明，應該留在適合維護它的地方；AGENTS.md 只提醒 agent 遵守重要的既有 boundary，必要時指向相關文件。而且，能用工具檢查的 boundary，就不該只靠一行規則來維持。像上面的第二條規則，就能交給檢查 import 的工具來把關。

AGENTS.md 可以提醒 agent 不要跨越 boundary，但不能代替 boundary 本身。

Choose：不寫原則，寫合作方式

階段三比較特殊。我們花了很多篇幅談 cohesion、information hiding、DRY、OCP、YAGNI 與 dependency topology，但這些原則不是永遠正確的指令，只是非常 high level 的 heuristic。

換句話說，設計原則就是前面說的模糊要求：它沒說何時適用，也沒說怎麼確認做對。所以我傾向不要把設計原則直接寫進 AGENTS.md。這也是 Day28 的結論：設計不只是遵守規則，更是在決定成本該付在哪裡。

這個階段更值得交代的，反而是你和 coding agent 的合作方式。例如在討論 plan 的時候，請 agent 主動提出這次改動會影響哪些 dependency，再一起討論 boundary 與 dependency 該怎麼設計。

因為 coding agent 不是你，你也沒辦法把腦中對專案的想法全部告訴它。新的 boundary 該放在哪裡、值不值得多一層 abstraction，仍然要根據這次 change 的需求與證據判斷：agent 負責把證據攤出來，判斷則留給你。

不過這種合作方式只有在討論設計時才用得到，不是每個任務都需要，所以也不一定要放在 AGENTS.md。

三個階段走下來，能寫進 AGENTS.md 的內容越來越少：Control 最明確，Contain 需要程式碼配合，Choose 幾乎不寫。

不值得預先載入的資訊，放哪裡？

AGENTS.md 不適合承載所有資訊，沒寫進去的內容其實大多已經有各自的位置。把前面的討論反過來整理，就是一份「不該交給 AGENTS.md」的清單：

這張表不是研究結論。只有第一列有直接的實驗支持 [1]，其餘是我依照前面四個問題整理出的判斷。

其中 Skills 值得多說一點。以 Codex 的 Skills [2] 為例，它採用 progressive disclosure：agent 一開始只知道 skill 的名稱與用途，任務需要時才載入完整的 SKILL.md。前面提到的設計討論流程就很適合做成 skill，平常不佔 context，討論設計時才載入。不過 Skills 也要被正確選用，不能假設 agent 一定會載入，所以它不能取代必要的強制檢查。

分類的依據不是內容長短，而是：這份資訊該在什麼時候被提供？ 每個任務都需要、而且必須提前知道的，才留在 AGENTS.md。

結語

回頭看，三個階段一直在處理不同形式的成本。Control 讓錯誤可以被發現與修正；Contain 讓理解與修改的範圍不必無限擴大；Choose 讓我們根據證據，決定哪些設計成本值得先付。

AGENTS.md 也一樣，因為 context 也是一種需要管理的資源。我們可以把整個 repo 的知識、規則與流程都寫進去，但不代表 agent 每次都需要。多一條規則，可能避免一次錯誤，也可能只是讓 agent 多做不必要的工作。

所以 AGENTS.md 的重點不是越完整越好，也不是越短越好。真正要決定的是：哪些資訊值得在任務開始前，就佔據 agent 的 context？

這個答案也不會永遠不變。repo 的架構、工具與工作方式改變時，原本必要的規則可能不再必要，甚至變成錯誤的資訊。AGENTS.md 需要跟著專案一起維護。

畢竟，Change has a cost. 我們不只要決定 code 該怎麼設計，也要決定哪些知識值得持續交給 AI。

參考資料

1. Gloaguen et al. (2026). Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? ICLR 2026 MemAgents Workshop.
2. Codex Skills 文件
3. AGENTS.md 官方網站