AGENTS.md 跨工具用途研究：GitHub Copilot、Claude Code、Cursor 與 CLI 怎麼讀它？

為什麼會有 AGENTS.md

配置文件分裂的歷史傷痕

在 2025 年中之前，如果你的團隊同時使用多個 AI 編碼工具，維護「讓 AI 了解這個 repo」的成本是乘法而非加法。Cursor 有 .cursorrules，GitHub Copilot 有 .github/copilot-instructions.md，Claude Code 有 CLAUDE.md，每個工具一套語法、一套放置規則、一套生效邏輯。

這個問題不是小煩惱。同樣一句「不要動 legacy/ 目錄」，你要在三個地方各寫一遍，而且格式還略有不同。團隊換工具的時候，過去積累的 AI 指令幾乎等於重寫。

AGENTS.md 就是在這個背景下誕生的。由 OpenAI 發起、Google Jules、Cursor、Amp、Factory 等工具廠商共同推動，2025 年中正式成為開放標準，並移交 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）管理。

定位：「README for agents」

AGENTS.md 的設計邏輯很清楚：README.md 是寫給人看的，AGENTS.md 是寫給 AI agent 看的。

具體來說，它解決的問題是：AI agent 開始一個任務時，需要什麼上下文才能「直接動手」而不是「先探索再猜測」？ 這包含建置指令、測試流程、程式碼風格規範、目錄結構說明、以及最重要的——哪些地方絕對不能動。

截至 2026 年初，GitHub 上已有超過 60,000 個 repo 使用 AGENTS.md，支援的 AI 工具超過 20 個。

常見誤解：AGENTS.md 不是取代所有配置

AGENTS.md 是共用底層，不是萬用替代品。如果你只用 Claude Code，CLAUDE.md 的功能更豐富（@imports、hooks、多層 scope）。如果你只用 Cursor，.cursor/rules/*.mdc 的目錄精度更高。AGENTS.md 的價值在於跨工具的共通基礎，進階工具特定設定仍由各自原生格式負責。

---

四個工具怎麼讀 AGENTS.md

GitHub Copilot Coding Agent：AGENTS.md 是雲端 Agent 的操作手冊

GitHub Copilot 有兩條 AI 路徑：inline Copilot（Chat + inline suggestion）和 Copilot Coding Agent（雲端 agent，可以被 assign issue 然後自主跑完整個任務）。

對 inline Copilot 來說，.github/copilot-instructions.md 是主要配置，AGENTS.md 也會被讀取，但後者更多服務於 Coding Agent。

對 Copilot Coding Agent 來說，AGENTS.md 是它開始任務前最重要的上下文來源之一——告訴它這個 repo 要怎麼 build、怎麼跑測試、有哪些慣例不能違反。GitHub 分析超過 2,500 個 repo 後，還另外推出了 .github/agents/*.agent.md 格式，讓你定義「專門角色的 agent」（例如 @docs-agent、@test-agent），每個 agent 有自己的 persona、工具邊界和可執行指令。

優先順序：.github/copilot-instructions.md（inline Copilot 主配置）、AGENTS.md（Coding Agent 主要讀取）、.github/agents/*.agent.md（自訂角色 agent）。

Claude Code：兩個文件都讀，CLAUDE.md 功能更豐富

Claude Code 是目前配置機制最複雜的工具。它同時讀取 AGENTS.md 和 CLAUDE.md，兩者都存在時會合併進入 context。

CLAUDE.md 是 Claude Code 的原生格式，功能明顯比 AGENTS.md 豐富：

• 多層 scope：managed policy（IT 全公司下發）→ project（repo 共用）→ user（個人偏好）→ local（本機私有）
• @imports：可以在 CLAUDE.md 裡用 @path/to/file 載入其他文件，最深 5 層
• auto memory：Claude 會自動把你的更正和偏好寫入記憶，不需要你手動維護
• pre/post hooks：可以在工具呼叫前後觸發自訂動作

官方建議 CLAUDE.md 維持在 200 行以內，超過會稀釋每行指令的遵從率。Claude Code 把這些文件視為 context，不是強制執行的配置——指令越具體清晰，遵從越穩定。

使用策略：如果你只用 Claude Code，把專案特定指令放進 CLAUDE.md，享受更豐富的功能。如果你同時使用多個工具，把通用指令放進 AGENTS.md，Claude Code 特有的進階設定再放 CLAUDE.md。

Cursor：從 .cursorrules 到跨工具標準的遷移

Cursor 的配置格式有個演化歷程：

• .cursorrules（已廢棄）：單一純文字文件，簡單好上手，但只對 Cursor 有效，也不支援目錄精度控制。2026 年已正式廢棄。
• .cursor/rules/*.mdc（現行原生格式）：目錄式、多文件、支援 glob scoping，可以只讓特定規則在特定目錄或文件類型生效。
• AGENTS.md（跨工具備援）：Cursor 在 2025 年加入支援，讓同一份 AGENTS.md 對 Cursor、Copilot、Codex 都有效。

使用策略：如果你的團隊只用 Cursor，投資在 .cursor/rules/*.mdc 的精細配置上。如果你的工具鏈混用，AGENTS.md 提供跨工具基礎，Cursor 特有的細粒度規則再用原生格式補充。

GitHub Copilot CLI / OpenAI Codex：AGENTS.md 是第一公民

對 OpenAI Codex CLI 而言，AGENTS.md 是唯一原生支援的指令格式（.cursorrules 和 CLAUDE.md 都不讀）。Codex 的讀取機制有明確的探索順序：

1. ~/.codex/AGENTS.override.md（使用者全域優先）
2. ~/.codex/AGENTS.md（使用者全域 fallback）
3. 從 repo root 往下走，每一層找 AGENTS.override.md → AGENTS.md，越深的目錄越晚讀、越高優先

關鍵限制：Codex 預設對 AGENTS.md 有 32 KiB 上限，超過的部分會被靜默截斷。這個限制讓「長篇大論」的 AGENTS.md 在 Codex 上有潛在風險。

衝突解決原則：最近（最深）的 AGENTS.md 優先 > 父目錄的 > 全域的。使用者在 chat 中的明確指令永遠覆蓋 AGENTS.md。

---

真正有效的 AGENTS.md 長什麼樣子

研究數據：寫對了能快 28.6%

Princeton 研究者在 10 個 repo、124 個 merged PR 上實測，分別在有 AGENTS.md 和沒有的情況下執行相同任務：

機制很直觀：沒有 AGENTS.md 時，agent 會花時間探索目錄結構、猜 build 系統、試測試指令。有 AGENTS.md 時，這些上下文預先提供，agent 直接進入解題。

GitHub 分析 2,500+ repos 的六個核心區塊

GitHub 工程師分析實際在用的 AGENTS.md 後，整理出高效文件的共通結構：

• Commands（指令）：放在最前面，包含完整 flag，不只是工具名稱。例如 pnpm test --reporter=verbose，而不是「用 pnpm 跑測試」。
• Testing（測試）：CI workflow 在哪、用什麼測試框架、PR 前必須通過哪些 check。
• Project structure（目錄結構）：哪些目錄是主要業務邏輯、哪些是 legacy 別動、哪些是自動產生的不用讀。
• Code style（程式碼風格）：與語言預設值不同的慣例才值得寫，例如「我們用 single quotes 而不是 double」。
• Git workflow（Git 流程）：commit message 格式、branch 命名、PR 前要跑什麼。
• Boundaries（邊界）：這是最有效果的部分——明確告訴 agent 哪些檔案絕對不能動，哪些操作要先問。

# AGENTS.md

## 建置與測試
- 安裝依賴：`pnpm install`
- 執行測試：`pnpm test`（PR 前必須全綠）
- 型別檢查：`pnpm type-check`

## 目錄說明
- `src/` — 主要業務邏輯
- `src/legacy/` — 舊程式碼，除非明確要求否則不要修改
- `generated/` — 自動產生，不要手動編輯

## 程式碼風格
- TypeScript strict mode 啟用
- 使用 single quotes，不加 semicolons
- 使用 named exports，避免 default export

## 邊界規則
- 🚫 不得修改 `src/legacy/` 的任何檔案
- 🚫 不得直接提交到 main branch
- ⚠️ 修改 `src/api/contracts/` 前必須確認是否影響下游

什麼不該放進 AGENTS.md

GitHub 的研究有個重要發現：把 README 內容複製進 AGENTS.md 反而有害，會讓任務成功率下降 23%（token 成本上升）。原因是冗餘內容稀釋了真正有用的指令，agent 的注意力是有限的。

不要寫進去的內容：

• 已經在 package.json scripts 裡的指令（agent 本來就會讀）
• 語言本身的標準慣例（agent 已知）
• 等同 README 的專案介紹段落
• 「寫乾淨的程式碼」這類無法驗證的原則

每一行都應該是「agent 從讀 code 和 package manifest 無法自行推斷」的資訊。

---

AGENTS.md vs. 各工具原生格式的選擇策略

四種格式的關鍵差異

決策框架

決定要不要投資 AGENTS.md，核心問題就一個：你的工具鏈是單一工具還是多工具？

情境 A：只用單一工具 用工具原生格式，功能最完整。Claude Code 用 CLAUDE.md、Cursor 用 .cursor/rules/*.mdc、Copilot 用 copilot-instructions.md。

情境 B：多工具混用，或 open source repo AGENTS.md 是主力。寫一份，多個工具都能讀。工具特定的進階設定再用原生格式補充。

情境 C：有 Monorepo AGENTS.md 天然支援分層：root 放全域規則，每個 package 子目錄放各自的 AGENTS.md，越深的越優先。

實務上的分層配置

以下是一個同時使用 Claude Code + GitHub Copilot + Cursor 的團隊的典型配置：

/repo
├── AGENTS.md              ← 共通規則（建置、測試、邊界）
├── CLAUDE.md              ← Claude Code 專屬（@imports、hooks、進階 scope）
└── .github/
    ├── copilot-instructions.md   ← Copilot Chat inline 指令
    └── agents/
        ├── docs-agent.agent.md   ← 文件撰寫專屬 agent
        └── review-agent.agent.md ← Code review 專屬 agent

AGENTS.md 的維護原則：把所有工具都需要知道的基礎設定放這裡，讓它成為新進工具（例如未來換用的 AI 工具）的「免費」起點。

---

結論

AGENTS.md 解決的是一個真實存在但容易被忽視的問題：當 AI coding agent 愈來愈多、愈來愈常被用在自主任務上，「如何讓 agent 理解這個 repo」就不應該是每個工具都要重複設定一遍的事。

研究數據支持它的有效性——寫得好的 AGENTS.md 可以讓 agent 任務快 28.6%、少用 16.6% token。但「寫得好」有具體條件：指令放在前面、用真實指令不用描述語言、明確設邊界、不要複製 README。

各工具的支援程度已相當成熟。OpenAI Codex 把它當第一公民，Claude Code 同時讀取 AGENTS.md 和 CLAUDE.md，Cursor 將它作為跨工具備援，GitHub Copilot Coding Agent 用它理解 repo 操作規範。如果你的工作環境涉及多個 AI 工具，現在是開始維護一份 AGENTS.md 的好時機——從 6 個核心區塊開始，20–30 行，先讓 agent 知道怎麼 build 和哪裡別動就夠了。

---

參考資料

• AGENTS.md 官方開放標準
• GitHub Blog：How to write a great agents.md (2,500 repos analysis)
• Anthropic Claude Code Memory Documentation
• morphllm：AGENTS.md vs CLAUDE.md 比較指南
• Princeton Study：AGENTS.md performance impact on OpenAI Codex (2025)