AGENTS.md 怎麼寫：規範、模板，以及 Cursor、Copilot、Trae、Kiro、Cline 各自怎麼讀

本文根據 AGENTS.md 官網和 Cursor、GitHub Copilot、Devin Desktop、TRAE、Kiro、Cline 各自的官方文檔整理，資料核對於 2026-10-11。Claude Code 的 CLAUDE.md 與 Codex 的讀取細節，見本站《CLAUDE.md 怎麼寫》，本文側重「一份文件給多種工具用」。

適用於誰

• 團隊裏有人用 Cursor、有人用 Copilot、有人用 Trae，不想每種工具維護一份規則的人；
• 搜「agents.md 怎麼寫」「agents.md 模板」「agents.md 規範」「agents.md 最佳實踐」的人；
• 已經有 .cursorrules、copilot-instructions.md，想知道要不要遷到 AGENTS.md 的人。

結論先說

1. AGENTS.md 是給編程智能體看的 README：一個放在倉庫裏的普通 Markdown 文件，寫構建步驟、測試命令和代碼約定。沒有必填字段，標題隨意。
2. 它是開放格式，官網稱已有 6 萬多個開源項目使用，現由 Linux 基金會下的 Agentic AI Foundation 管理。
3. 通用規則：放在倉庫根目錄；大倉庫可以在子目錄裏再放，離被編輯文件最近的那份優先；你在對話裏的明確指示高於一切。
4. 主流工具大多自動讀取，但有例外：Trae 要手動打開開關，Gemini CLI 和 Aider 要改配置。
5. 推薦做法：通用約定只寫在 AGENTS.md 裏，各工具專屬的規則文件只放該工具獨有的內容。

各工具怎麼讀 AGENTS.md

寫什麼

官網列出的常見小節：項目概覽、構建和測試命令、代碼風格、測試說明、安全注意事項；再加上提交資訊和 PR 規範、安全上的坑、部署步驟——任何你會告訴新同事的東西。

一份可以直接改寫的中文模板：

markdown
# AGENTS.md

## 項目概覽
Next.js 14 + TypeScript 的電商後台；數據庫 Prisma + MySQL；包管理用 pnpm。

## 常用命令
- 安裝依賴：`pnpm install`
- 本地啟動：`pnpm dev`
- 類型檢查：`pnpm typecheck`
- 單元測試：`pnpm test`；只跑一個用例：`pnpm vitest run -t "用例名"`

## 代碼約定
- TypeScript 嚴格模式；組件用具名導出
- 金額一律用「分」為單位的整數
- 新接口先寫入參校驗，再寫業務邏輯

## 測試要求
- 改了代碼就要補或改對應的測試，即使沒人要求
- 提交前類型檢查和測試必須全部通過

## 不要碰
- `src/generated/`、`prisma/migrations/` 下的已有文件
- 任何 `.env*` 文件；需要新的環境變量時告訴我，不要自己寫

## 提交與 PR
- 提交資訊用中文，格式「類型: 簡述」
- 一個 PR 只做一件事

官網 FAQ 裏有一條值得知道：寫在 AGENTS.md 裏的測試命令，智能體會自動去跑——它會嘗試執行相關檢查，並在結束任務前修復失敗項。所以命令要寫準確、可直接執行。

寫多長、怎麼分

• 只寫會被反覆用到的。幾家官方的建議是一致的：Cursor 說規則應聚焦、可執行，不要照抄整份代碼規範（交給 linter）；GitHub 給 cloud agent 生成指令的提示詞把篇幅限制在兩頁以內。
• 大倉庫用嵌套。在每個子包裏放一份 AGENTS.md，智能體讀最近的那份。官網舉例說 OpenAI 的主倉庫裏有 88 個 AGENTS.md。
• 當作活文檔。智能體反覆犯同一個錯，就把糾正寫進去。

text
project/
  AGENTS.md              # 全局約定
  frontend/
    AGENTS.md            # 前端專屬
  backend/
    AGENTS.md            # 後端專屬

一個倉庫多種工具：只維護一份

第一層：AGENTS.md 放通用內容。命令、目錄、約定、禁區——換任何工具都成立的東西。

第二層：各工具的專屬文件只放專屬內容。

GitHub 官方文檔對這種分工有一句很好的概括：copilot-instructions.md 是「Copilot，在這個倉庫裏始終記住這些」，AGENTS.md 是「任何智能體都記住這些」。

從舊文件遷移：官網給的做法是改名並留一個符號連結保持兼容，例如：

bash
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Cline 會自動識別 .cursorrules 和 .windsurfrules，Devin Desktop 仍讀取舊的 .windsurfrules，所以遷移可以慢慢來，不必一次改完。

常見問題

Q：指令衝突時聽誰的？

離被編輯文件最近的 AGENTS.md 優先；你在對話裏明確說的話高於文件。工具自己的規則文件和 AGENTS.md 之間的優先級各家不同（例如 Cursor 是團隊規則 → 項目規則 → 用戶規則依次合併），所以最好的辦法是不要讓它們寫同一件事。

Q：AGENTS.md 裏能放密鑰、內部地址嗎？

不要。它會隨倉庫提交，也會被原樣送進模型上下文。需要的憑據放環境變量，文件裏只寫變量名。

Q：別人倉庫裏的 AGENTS.md 可以直接信嗎？

要先看一眼。它就是會被智能體執行的指令，來歷不明的倉庫裏可能寫着讓智能體執行危險命令的內容。Kiro 的文檔在講多倉庫任務時專門提醒：只選你信任的倉庫，因為智能體會遵循倉庫裏的指示。更多見《AI 編程安全注意事項》。

Q：有沒有現成的規則和技能可以參考？

本站的 Skill 庫 收錄了一批公開的技能與規則倉庫，可以按語言和用途挑着看，再改成適合自己項目的版本。

參考資料

• AGENTS.md 官網：https://agents.md/
• Rules（Cursor 官方）：https://cursor.com/docs/rules
• Adding repository custom instructions for GitHub Copilot（GitHub 官方）：https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions
• Memories & Rules（Devin Desktop 官方）：https://docs.devin.ai/desktop/cascade/memories
• 規則（Rule）（TRAE 官方）：https://docs.trae.ai/ide/rules
• Steering（Kiro 官方）：https://kiro.dev/docs/steering
• Rules（Cline 官方）：https://docs.cline.bot/customization/cline-rules