AGENTS.md

是什麼 ?

AGENTS.md 是一個專門設計給 AI 程式助理 (coding agents) 的文件格式

README 的「機器人版本」：

• README 是給人類開發者看的
• AGENTS.md 則是要讓 AI 工具在處理程式碼時，能快速理解專案的規則和操作方式

⇒ 它的形式就是普通的 Markdown，所以撰寫、維護都很方便。

為什麼需要

在傳統專案裡，README 通常只寫「專案介紹、安裝方式、快速開始」等資訊，偏向人類開發者理解。 但是對 AI 來說，它需要的其實是更細節的規則與步驟：

• 要怎麼建置和測試？
• 程式碼風格要遵守哪些規則？
• commit message 和 PR 要怎麼寫？
• 哪些地方涉及安全性，不能亂改？

如果沒有這些資訊，agent 可能會做錯事，例如執行錯的測試、提交不合規的程式碼，甚至誤觸敏感資料。AGENTS.md 的目的，就是補上這個缺口。

可以放什麼

AGENTS.md 不需要長篇大論，但內容要精確、具體，能直接讓 agent 執行。常見的結構包括：

• 專案概覽：這個專案的用途與主要模組，讓 agent 知道整體方向。
• 建置與測試指令：明確列出 build、test、deploy 的指令，方便 agent 在修改後自動檢查程式是否正常。
• 程式碼風格規則：像縮排方式、命名慣例、是否強制型別標註、要不要跑 linter 等。
• PR / Commit 準則：告訴 agent commit message 或 PR 標題該怎麼寫、流程有哪些檢查步驟。
• 安全注意事項：提醒 agent 哪些檔案或參數不能修改，例如 .env、金鑰、機敏 API。
• 子專案規則：如果是 monorepo（大型專案分多模組），可以在每個子目錄也放 AGENTS.md，agent 會依照「就近原則」讀取最相關的版本。

使用方式

1. 在專案根目錄新增 AGENTS.md。
2. 把 agent 在開發過程「一定會需要」的資訊寫清楚，避免模糊的描述（例如「請遵守風格」應改成「統一使用 PEP8，必要時跑 flake8」）。
3. 如果專案很大，可以在子資料夾再放 AGENTS.md，agent 會優先採用距離最近的規則。
4. 當使用者下指令與 AGENTS.md 衝突時，就近原則 > 使用者明確指令，確保不會混亂。

好處

• 減少錯誤：agent 不會亂跑錯的指令或提交不合規程式。
• 提高效率：agent 能自動完成測試與檢查，減少人工干預。
• 文件分工清楚：人類看 README，AI 看 AGENTS.md，不會互相干擾。
• 適合多人協作、大型專案：尤其是 monorepo，可以避免 agent 在不同模組間混淆規則。

注意

• 要持續更新：如果程式流程改變、測試方式不同，一定要同步修改 AGENTS.md。
• 描述要具體：避免使用「大概、盡量」這種模糊字眼，agent 需要能夠「直接照做」。
• 維護成本：太簡略，agent 會做錯；太冗長，人類和 agent 都難以維護。建議精準、必要就好。