---
# System prepended metadata

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

---

# 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