# AGENTS.md：AI 編碼代理的專用指南

官網： **[agents.md](https://agents.md/)**

## 重點摘要

* **定義與目的**：AGENTS.md 是一個簡單、開放的格式，用於指導 AI 編碼代理，類似於代理的 README 檔案。它提供專用且可預測的位置，為 AI 編碼代理提供專案的上下文和指令。
* **與 README.md 的區別**：
* `README.md` 專為人類設計，包含快速入門、專案描述和貢獻指南。
* `AGENTS.md` 則補充了這些內容，提供 AI 編碼代理所需的額外詳細上下文，例如建置步驟、測試和程式碼慣例，這些內容可能使 `README.md` 變得混亂或與人類貢獻者無關。
* 它旨在為代理提供清晰、可預測的指令位置，同時保持 `README.md` 的簡潔性。
* **兼容性與生態系統**：AGENTS.md 是一個開放格式，與不斷成長的 AI 編碼代理和工具生態系統兼容，包括 OpenAI 的 Codex、Google 的 Amp 和 Jules、Cursor、Factory 等。
* **使用方式**：
1. 在儲存庫的根目錄創建 `AGENTS.md` 檔案。
2. 包含有助於代理有效工作的區塊，例如專案概述、建置和測試指令、程式碼風格指南、測試說明、安全考量等。
3. 添加額外指令，如提交訊息或拉取請求指南、安全注意事項、大型資料集、部署步驟等。
4. 對於大型單一儲存庫 (monorepo)，可以在子專案中嵌套 `AGENTS.md` 檔案，最接近編輯檔案的 `AGENTS.md` 將優先。
* **內容範例**：頁面提供了設置指令（如 `pnpm install`）、程式碼風格（TypeScript 嚴格模式、單引號、無分號）、開發環境提示、測試指令和 PR 指令的具體範例。
* **常見問題**：
* 沒有強制性欄位，它只是標準的 Markdown。
* 如果指令衝突，最接近編輯檔案的 `AGENTS.md` 優先；使用者聊天提示則覆蓋一切。
* 代理會嘗試自動執行列出的測試指令並修復失敗。
* 可以隨時更新，視為活文檔。
* 遷移現有文檔時，可將其重命名為 `AGENTS.md` 並創建符號連結以保持向後兼容。

## 總結

AGENTS.md 是一個創新且實用的開放格式，旨在優化 AI 編碼代理在軟體專案中的工作流程。透過為代理提供專門、結構化且可預測的指令集，它有效彌補了傳統 `README.md