如何為程式開發代理撰寫 AGENTS.md 檔案
撰寫一份簡短的 AGENTS.md，列出安裝與測試指令、規則和界線，讓 Claude Code 和 Gemini CLI 載入它，再用小任務測試。
AGENTS.md 是放在儲存庫根目錄的純 Markdown 檔案，告訴程式開發代理該如何處理這個專案：要執行哪些指令、程式碼放在哪裡，以及哪些東西不要動。它沒有必填的章節。保持簡短，讓每條規則都能檢查，並確認每個代理都有載入它。
本文說明該寫些什麼、提供一份範本，並介紹 Claude Code 和 Gemini CLI 如何找到這個檔案，最後附上一個快速測試。當你用 Reunified 的 Mono 從手機啟動代理時，步驟也一樣。
1. 決定檔案裡該放什麼
agents.md 網站把它稱為給代理看的 README。放入每個工作階段都需要的資訊，代理能從程式碼中得知的內容就省略。
| 寫進 AGENTS.md | 不要寫進去 |
|---|---|
| 安裝、測試與 lint 指令 | 密碼、API 金鑰與權杖 |
| 主要程式碼的位置 | 完整的檔案樹或相依套件清單 |
| 與預設不同的慣例 | 冗長的流程（改為連結到文件） |
| 絕不能編輯的檔案、需要先詢問的動作 | 個人偏好（改用代理的使用者層級檔案） |
在 monorepo 中，你可以在每個套件裡各放一份 AGENTS.md。距離最近的檔案優先，而你在對話中直接下的指示又會優先於它。
2. 從簡短的範本開始
以下是虛構的「tidy-recipes」範例，這是一個使用 pnpm 的 TypeScript 網頁應用程式：
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.只列出你在這個儲存庫中實際執行過的指令。指令寫錯了，代理也會照單全收。
3. 寫出代理能檢查的規則
好的規則能讓你事後檢查代理有沒有遵守。
| 模糊 | 具體 |
|---|---|
| 測試你的變更 | 完成前執行 pnpm test 和 pnpm lint |
| 讓檔案保持有條理 | 元件放在 src/components |
| 小心處理資料庫 | 絕不編輯 db/migrations/ |
| 總結你的工作 | 列出修改過的檔案和測試結果 |
把界線寫成「絕不」和「先詢問」的規則，一行一條。
4. 讓 Claude Code 和 Gemini CLI 讀取它
agents.md 網站列出了支援這個格式的 Codex、Gemini CLI、opencode 和其他代理，但有些需要先調整設定。
在預設情況下，較新版本的 Claude Code 只有在工作目錄或其上層目錄中沒有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 時，才會讀取 AGENTS.md（參見 Claude Code 的記憶功能文件）。如果你有其中一個檔案，或使用的是較舊的版本，就從 CLAUDE.md 匯入 AGENTS.md。tidy-recipes 專案有一份舊的 CLAUDE.md，所以在檔案最上方加入這一行，並把只給 Claude 看的說明留在下方：
@AGENTS.md
Prefer small commits.開始新的工作階段，執行 /context，確認 CLAUDE.md 出現在 Memory files 底下。如果沒有 CLAUDE.md，/memory 會改為列出 AGENTS.md 的路徑。
Gemini CLI 預設讀取 GEMINI.md。若要加入 AGENTS.md，把以下內容放進專案的 .gemini/settings.json（參見 Gemini CLI 的 GEMINI.md 文件）：
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}開始新的工作階段，再執行 /memory show 查看載入了哪些內容。其他代理請查看各自的文件。
5. 用小任務測試這個檔案
在新的工作階段中，給代理這項任務：
先列出你載入的專案規則，以及每條規則來自哪個檔案。然後把 src/components/SaveButton.tsx 中的按鈕文字「Save recipe」改成「Save」。其他什麼都不要改。
對照檔案檢查結果：
- 它提到了 AGENTS.md（或含有匯入的 CLAUDE.md）。
- 它執行了
pnpm test和pnpm lint，並回報結果。 - 它沒有動 db/migrations/，也沒有新增相依套件。
- 它列出了修改過的檔案。
自己用 git diff 確認修改內容（見審查 AI 程式碼變更）。如果代理說不出某條規則，檔案可能沒有載入，請回到第 4 步。如果它說出了規則卻沒有遵守，就把規則寫得更具體。
6. 保持簡短並隨時更新
Claude Code 的文件建議 CLAUDE.md 不要超過 200 行，因為檔案越長，占用的上下文越多，代理也越難確實遵守。AGENTS.md 也以同樣的長度為目標。上下文視窗指南說明了上下文填滿時會發生什麼事。
代理重複犯同樣的錯誤時就更新檔案，並刪除過時的指令和互相衝突的規則。把它提交到儲存庫，並像審查程式碼一樣審查對它的修改。
這個檔案只是引導代理，並不會強制執行任何事。若要阻止某個動作，請使用代理的權限設定，或拒絕它的要求（見工具權限指南）。
在 Mono 中，代理會在你電腦上專案的工作目錄中啟動，並在那裡尋找這些檔案。你可以在 Mono 的編輯器中開啟 AGENTS.md、CLAUDE.md 或 .gemini/settings.json，用手機也可以，編輯內容會自動儲存。若要建立這個檔案，可以請代理建立，或從專案卡片開啟終端機。Mono 不會檢查這個檔案，也不會改變代理載入哪一個檔案。Mono 還沒有正式推出，但你可以加入候補名單。
