昨天我發布了企業團隊的 CLAUDE.md 指南。幾小時內，三個人問了同一個問題：「那麼並非全部採用 Claude Code 的團隊呢？」

合理的質疑。如果您的組織某些團隊使用 GitHub Copilot、其他團隊使用 Cursor、背景任務使用 Codex，而複雜重構使用 Claude Code—而且這種情況日益普遍—您需要某種能在所有工具間通用的方案。

那就是 AGENTS.md。

AGENTS.md 是什麼（以及不是什麼）

AGENTS.md 是一個供應商中立的 markdown 檔案，告訴 AI 編碼代理如何在您的程式碼庫中工作。它位於您的存放庫根目錄（或在子目錄中用於範圍限定的規則），包含與您第一天報到時給新進開發者的相同資訊：建置命令、測試流程、編碼慣例、專案架構與明確邊界。

與 README.md 的關鍵差異在於：它是為機器結構化，而非為人類。README 可能會說「我們使用 React 搭配 TypeScript」，而 AGENTS.md 則會說：

## Tech Stack
- React 18.3, TypeScript 5.4, Vite 5.2, Tailwind CSS 3.4

確切版本。沒有敘述。代理不需要您的起源故事。

這個格式源自一個實際問題。在 AGENTS.md 出現前，每個代理都有自己的設定檔—Aider 使用 CONVENTIONS.md、Roo Code 使用 .roomodes 檔案、Cline 使用 .clinerules 目錄，而 Claude Code 使用 CLAUDE.md。執行多個代理的團隊維護著冗餘、分歧的設定。AGENTS.md 將此統一為單一真相來源，現已有超過 60,000 個開源專案採用。

為何企業團隊應該重視

數字會說話。GitHub 分析了超過 2,500 個存放庫，發現代理成功率在適當指引下會大幅躍升：

  • 無 AGENTS.md — 40-60% 任務成功率
  • 最小 AGENTS.md — 60-70% 成功率
  • 完整 AGENTS.md — 85-90% 成功率

對於一個早上排隊五個代理任務的企業團隊（WorkOS 團隊以 Codex 開創的模式），這就是每天兩次失敗與零失敗的差別。乘以您整個組織，ROI 就顯而易見。

但真正的企業價值不僅是成功率。而是跨工具的標準化。當您的前端團隊使用 Cursor、平台團隊使用 Claude Code，而 DevOps 團隊試驗 Codex 時，單一 AGENTS.md 確保他們都遵循相同的慣例。撰寫一次，每個代理都會讀取。

各主要代理如何使用 AGENTS.md

並非所有代理都以相同方式消耗 AGENTS.md。了解差異有助於您撰寫在各處都能良好運作的檔案。

GitHub Copilot

Copilot 會從工作區根目錄與子目錄自動探索 AGENTS.md。GitHub 團隊分析那 2,500+ 個存放庫，正是為了改善 Copilot 解譯此格式的方式。Copilot 也支援 .agent.md 檔案—一種獨立格式，使用 YAML frontmatter 定義具有特定工具與角色的自訂代理角色設定。

Cursor

Cursor 會自動探索 AGENTS.md 並將其饋送至其指令系統。無需設定—將檔案放入您的存放庫，Cursor 就會拾取它。簡單且有效。

Windsurf

Windsurf 擁有最精密的整合。它將 AGENTS.md 視為其 Rules 引擎的一部分，具有自動範圍界定：根目錄檔案成為永遠開啟的全域規則，而子目錄檔案會根據其位置自動套用 glob 模式。Windsurf 會掃描您整個工作區中的所有 AGENTS.md 檔案。

Claude Code

Claude Code 支援 AGENTS.md，並搭配其原生的 CLAUDE.md 格式。兩者互補—AGENTS.md 用於通用慣例，CLAUDE.md 用於 Claude 特定功能，如自動記憶、MCP 伺服器宣告，以及我在 Claude Code 專案剖析中介紹的三層架構。

OpenAI Codex

Codex 在啟動時自動探索並載入 AGENTS.md，在任務執行期間頻繁引用命令。這正是 WorkOS 案例研究出色之處—他們的團隊每天早上為 Codex 排隊 4-5 個維護任務（TypeScript 修正、Webhook 更新、驗證移轉），並在範圍明確的工作上報告 85-90% 的成功率。

Aider

Aider 已透過 --conventions-file 支援慣例檔案。AGENTS.md 成為標準預設位置，而現有的 CONVENTIONS.md 檔案仍可向後相容地運作。

其他

Roo Code、Google Jules、Factory.ai Droids 與 Zed 都支援 AGENTS.md，精密程度各異。Factory.ai 將其作為主要簡報機制，具有跨目錄的全面探索。趨勢很明確：AGENTS.md 正成為基本門檻。

每個 AGENTS.md 需要的六件事

GitHub 對 2,500+ 個存放庫的分析識別出六個產生最大差異的核心領域：

1. 可執行命令

將這些放在最前面。代理會不斷使用它們。

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test all: `pnpm test`
- Test single: `pnpm test -- --grep "test name"`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

2. 測試指示

不僅是如何執行測試，還包括如何撰寫測試。使用什麼框架、什麼模式、它們位於何處。

## Testing
- Framework: Vitest with React Testing Library
- Location: `__tests__/` directories adjacent to source
- Pattern: one test file per component, named `ComponentName.test.tsx`
- Run single file: `pnpm test src/components/__tests__/Button.test.tsx`

3. 專案架構

帶有簡短註解的檔案結構。代理使用這個來導覽不熟悉的程式碼庫。

## Architecture
- `src/api/` — .NET 8 Web API (Clean Architecture)
- `src/web/` — React 18 + TypeScript frontend
- `src/shared/` — Shared types and utilities
- `infra/` — Terraform modules and Bicep templates
- `scripts/` — CI/CD and automation scripts

4. 程式碼風格（含範例）

抽象規則無法落地。具體範例才行。

## Code Style
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- Example:
  ```tsx
  export function UserCard({ name, role }: UserCardProps) {
    const [expanded, setExpanded] = useState(false);
    return (
      <Card onClick={() => setExpanded(!expanded)}>
        <h3>{name}</h3>
        {expanded && <p>{role}</p>}
      </Card>
    );
  }
  ```

5. Git 工作流程

提交標準、分支慣例、PR 需求。

## Git Conventions
- Commit format: `type(scope): description` (conventional commits)
- Branch naming: `feature/JIRA-123-brief-description`
- PRs require passing tests and lint checks

6. 明確邊界

三層約束結構對企業團隊至關重要：

## Boundaries
**Always do:**
- Include unit tests for new functions
- Run lint before committing
- Use environment variables for configuration

**Ask first:**
- Database schema changes
- Adding new dependencies
- Modifying CI/CD pipelines
- Changes to authentication or authorization logic

**Never do:**
- Commit secrets, API keys, or connection strings
- Modify files in `vendor/` or `node_modules/`
- Edit generated migration files
- Push directly to main branch
- Modify `.env.production`

Monorepo 模式

這是 AGENTS.md 對企業團隊而言變得有趣之處。此格式支援階層式巢狀—子目錄檔案繼承並覆寫父檔案，最接近的檔案優先。

/AGENTS.md                          ← Global: security rules, commit conventions
/frontend/AGENTS.md                 ← React patterns, CSS conventions, component rules
/frontend/components/AGENTS.md      ← Component library specifics
/backend/AGENTS.md                  ← API patterns, database rules, service conventions
/infra/AGENTS.md                    ← Terraform/Bicep rules, naming conventions

OpenAI 在其存放庫中維護約 88 個巢狀 AGENTS.md 檔案。這並不過度—而是精確。每個團隊擁有其子目錄的代理指引，而全域規則從根目錄向下層疊。

對企業團隊而言，這自然對應到團隊擁有權。平台團隊擁有根目錄層級規則。前端、後端與基礎結構團隊擁有各自的子目錄檔案。變更透過提取請求進行，就像程式碼一樣。

AGENTS.md、CLAUDE.md 與 SKILL.md — 它們如何搭配

如果您正在使用 Claude Code（如果您閱讀了我們的 CLAUDE.md 指南，您很可能是），您可能想知道這些檔案之間的關係。以下是心智模型：

  • AGENTS.md —「如何在此程式碼庫中工作。」供應商中立。每個代理都會讀取。包含命令、架構、慣例與邊界。

  • CLAUDE.md —「Claude 特別應該如何在此工作。」僅限 Claude Code。新增自動記憶、MCP 伺服器宣告、掛鉤設定與 Claude 特定最佳化。

  • SKILL.md —「如何執行此類別的任務。」可重複使用的專業套件—並非程式碼庫特定，而是任務特定。我在我們關於 Claude Code 與 Gemini CLI 技能工具的文章中介紹了技能建立工作流程。

將它想像成一個堆疊：

  • 系統提示 — 模型基準（您無法控制這個）
  • AGENTS.md — 程式碼庫上下文（通用）
  • SKILL.md — 任務專業（按需）
  • CLAUDE.md / .agent.md — 代理特定設定（按工具）
  • MCP 伺服器 — 外部系統存取（即時資料）

對於多元代理團隊，將大部分心力投資在 AGENTS.md。它有最廣的觸及範圍。然後再疊加 CLAUDE.md 或 .agent.md 檔案以進行代理特定最佳化。

企業入門範本

以下是適合企業團隊的現成複製貼上範本。自訂細節，保留結構：

# AGENTS.md

## Project Overview
[One sentence: what this system does and who it serves]

## Tech Stack
- [Language] [version], [Framework] [version], [Build tool] [version]
- Database: [system] [version]
- Infrastructure: [platform] (Terraform/Bicep/CDK)
- CI/CD: [platform]

## Commands
- Install: `[command]`
- Dev: `[command]`
- Build: `[command]`
- Test all: `[command]`
- Test single: `[command] [path]`
- Lint: `[command]`
- Format: `[command]`

## Architecture
- `src/` — Application source code
  - `src/api/` — [description]
  - `src/web/` — [description]
  - `src/shared/` — [description]
- `infra/` — Infrastructure as code
- `tests/` — Integration and E2E tests
- `scripts/` — Automation and CI/CD
- `docs/` — Architecture decisions and runbooks

## Code Style
- [2-3 concrete rules with examples]
- Example:
  ```[language]
  // Preferred pattern
  [code example]
  ```

## Testing
- Framework: [name]
- Location: [pattern]
- Naming: [convention]
- Coverage: [minimum threshold if any]

## Git Conventions
- Commits: [format]
- Branches: [naming pattern]
- PRs: [requirements]

## Boundaries
**Always do:**
- [list critical always-do items]

**Ask first:**
- [list items requiring human approval]

**Never do:**
- [list absolute prohibitions]

在 15 分鐘內開始

您不需要在第一天就有完美的 AGENTS.md。從最小開始並反覆調整。

步驟 1（5 分鐘）： 在您的存放庫根目錄建立 AGENTS.md。加入您的建置、測試與 lint 命令。這些具有最高的立即影響。

步驟 2（5 分鐘）： 加入含確切版本的技術堆疊，以及列出您目錄結構的簡短架構章節。

步驟 3（5 分鐘）： 加入邊界章節。從「絕不」開始—如果代理做了會造成真正損害的事。為需要人工判斷的事項新增「先詢問」項目。

步驟 4（持續進行）： 每次代理犯錯，就新增一條規則。這是每個成功團隊遵循的有機成長模式。您的 AGENTS.md 會成為經驗教訓的活記錄。

專業提示： 有一個社群維護的提示，要求 AI 代理掃描您現有的存放庫—套件檔案、CI/CD 工作流程、貢獻指引、git 歷史—並自動產生起點 AGENTS.md。這是現有專案最快速的啟動方式。

多元代理的現實

以下是這件事現在很重要的原因。AI CLI 戰爭意味著您的團隊可能已經在使用多個代理，無論您是否核准。開發者選擇最適合當前任務的工具—Cursor 用於互動式編輯、Claude Code 用於複雜重構、Codex 用於背景任務佇列。

沒有 AGENTS.md，每個開發者會獨立設定每個代理。慣例會漂移。品質會參差不齊。同樣的錯誤會由不同代理在程式碼庫的不同部分重複發生。

有了 AGENTS.md，您只需定義一次標準。每個代理、每個開發者、每個工作階段都從相同基準開始。這就是企業價值主張：不是選擇一個代理，而是讓所有代理一致地運作。

資源

把您的多元代理策略做對

AGENTS.md 是基礎，但它只是更廣泛 AI 編碼策略的一環。它如何與您的 CLAUDE.md 檔案搭配？您的 MCP 伺服器基礎結構？您的治理需求？您團隊的實際工作流程？

Big Hat Group 協助企業團隊建構連貫的 AI 代理策略—不僅是設定檔，而是完整堆疊：代理設定、技能開發、安全邊界，以及讓合規團隊安心的治理框架。我們已在同時執行 Copilot、Claude Code 與 Codex 的組織中部署這些模式。

如果您的團隊正在同時應對多個 AI 編碼代理且需要統一的方法，請與我們聯絡。

Kevin Kaminski 是 Microsoft MVP，也是 Big Hat Group 的負責人，在該處他協助企業團隊部署 AI 代理、Windows 365 與現代化管理解決方案。