AGENTS.md 是什麼？如何在 30 分鐘內撰寫自己的檔案

關於氛圍編碼與使用代理程式的實用資料：Ailoot 文件。

用一段話認識 AGENTS.md#

以下將參考 agents.md、OpenAI Codex 文件、JetBrains Junie、Cursor Rules Docs、GitHub Copilot Coding Agent 變更日誌，以及 Linux Foundation 關於 Agentic AI Foundation 的新聞稿來說明這種格式。所有數據與功能截至 2026 年 5 月 30 日；Claude Code 對 AGENTS.md 的支援則依據 Anthropic 文件，並納入 2026 年 9 月 24 日的更新。

如果你不了解市面上這一大群工具是什麼，也不知道為什麼它們需要共用檔案，請先閱讀指南「2026 年用什麼來寫程式：從 Claude Code 到 Antigravity 的 8 種 AI 工具」。本文專門介紹 AGENTS.md 格式，以及如何在 30 分鐘內撰寫自己的檔案。

AGENTS.md 是什麼？它從何而來？#

過去每種 AI 工具都有自己的規則檔案：Anthropic 有 CLAUDE.md、Cursor 有 .cursorrules、GitHub 有 .github/copilot-instructions.md、Aider 有 .aider.conf.yml，JetBrains 則有 .junie/guidelines.md。如果團隊有三種不同的代理程式，就得維護三份內容相同的檔案，而它們往往一週內就會開始出現差異。

OpenAI 是第一個受不了這種情況的公司。2025 年 8 月，它發布了 Codex CLI，並同時推出開放格式 agents.md。網站上寫道：

「把 AGENTS.md 想成是給代理程式看的 README。」

（agents.md，由英文翻譯）

重點是，AGENTS.md 是 README 的補充。README 是寫給人看的：「專案是什麼、如何在本機執行、如何參與貢獻。」AGENTS.md 則是寫給代理程式看的：精確的 Shell 指令、可驗證的「完成」標準，以及「絕對不要碰這裡」之類的界線。

網站上寫道：

「AGENTS.md 是 README 的補充：它記錄代理程式需要的額外資訊，有時甚至是詳細資訊，例如建置步驟、測試和慣例。這些內容放在 README 會顯得雜亂，或根本不是人類貢獻者所需的資訊。」

（agents.md，由英文翻譯）

到了 2025 年 9 月，GitHub Copilot Coding Agent 已支援這種格式（變更日誌，2025 年 8 月 28 日）。到了 12 月，Cursor、Junie、Gemini CLI、Aider 等十多種工具也加入了。2025 年 12 月 9 日，Linux Foundation 成立了 Agentic AI Foundation（AAIF）：三個創始專案分別是 OpenAI 的 AGENTS.md、Anthropic 的 MCP，以及 Block 的 goose。創始成員包括 AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft 和 OpenAI。到了 2026 年 2 月 24 日，基金會已納入146 個組織，包括 Red Hat、ServiceNow、Akamai、Lenovo、JPMorgan Chase、Huawei、UiPath 和 Hitachi。

從那時起，AGENTS.md 就不再是「又一個 OpenAI 的東西」，而成為事實上的標準。

哪些 AI 代理程式會讀取 AGENTS.md？哪些不會？#

截至 2026 年 5 月 30 日的支援狀況；Claude Code 一列於 2026 年 9 月 24 日更新：

Anthropic 是最後加入的主要業者。2025 年 8 月，官方 anthropics/claude-code 儲存庫中開啟了 issue #6235，要求支援 AGENTS.md。

這個 issue 開啟了將近一年，於 2026 年 8 月 17 日關閉；支援 AGENTS.md 的 2.1.277 版則在 9 月 18 日推出。Anthropic 的邏輯如下：CLAUDE.md 優先；只有在工作資料夾或任何上層資料夾都沒有 CLAUDE.md 時，才會讀取 AGENTS.md。根據文件，運作方式如下：

要注意的是，個人用的 CLAUDE.local.md 也算在內；有了它，Claude Code 就會停止讀取 AGENTS.md。你可以在 /config 的 Project instructions 中變更這項行為，例如讓 Claude Code 同時讀取兩個檔案。在低於 2.1.277 的版本中，AGENTS.md 不會自動載入；在 CLAUDE.md 中加入 @AGENTS.md 這一行仍是替代方法。

AGENTS.md 與 CLAUDE.md、.cursorrules 有什麼不同？#

截至 2026 年 5 月 30 日的四種格式比較：

AGENTS.md 可放共通專案指示，但每個用戶端的載入途徑及個人設定仍需分別設定。Claude Code 可用 CLAUDE.local.md，Cursor 則有使用者層級的本機 .mdc 檔案。AGENTS.md 本身不提供這項功能；你需要搭配其他檔案，或與團隊約定把個人規則寫在會被 gitignore 的區段中。

另一個重要細節是 monorepo。Codex 和 Cursor 採用「最近的 AGENTS.md 優先」這項規則：

「在 monorepo 中，請在每個套件內放置個別的 AGENTS.md。代理程式會自動讀取目錄樹中最近的檔案，並以最近的檔案為準。」

（agents.md，由英文翻譯）

agents.md 提到，OpenAI 的主要 monorepo 有 88 個 AGENTS.md，分別供不同子套件使用。如果你在 monorepo 中工作，請將規則分層：根目錄放一般規則，子資料夾放特定規則。

好的 AGENTS.md 應該包含什麼？#

agents.md 網站提供彈性的格式——「任何 Markdown 都可以」。但實際上，80% 的優質檔案都包含相同的八個章節。主要原則是每個項目都應該是精確指令或具體範例。「撰寫整潔的程式碼」這類抽象想法會被代理程式忽略。

1. 專案概覽 — 2–3 行。說明專案內容、對象及主要目標。不寫行銷文案。範例：「用於引導使用者加入付費工作坊的 Telegram 機器人。技術堆疊：Next.js 14、Prisma、PostgreSQL。purchases 新增記錄時觸發。」
2. 設定指令 — 在本機執行的精確 Shell 指令。npm install、npm run dev、npm run build。不要寫「我們通常都這麼做」。
3. 程式碼風格／慣例 — 寫出具體規則和範例，不要只說「寫得整潔」。例如：「TypeScript strict、單引號、不使用 default exports、元件名稱採 PascalCase、hooks 以 use 開頭。」
4. 開發環境提示 — 重要資訊的位置。.env 需要哪些變數、密鑰存在哪裡、使用哪些連接埠，以及如何操作本機 DB。
5. 測試指示 — 如何執行特定測試，以及何謂「通過」。例如：npm test -- --testPathPattern=user-auth；預期全部 100% 通過。
6. PR／commit 規範 — commit 訊息格式、提交 PR 前的檢查清單（測試、linter、文件），以及核准者。
7. 安全注意事項 — 絕對不能發生的事。「絕不提交 .env。密鑰只能存放在 Vault。不要在日誌中顯示使用者個人資料。」
8. 界線／絕對不要做的事 — 禁止事項要附上替代方法。「不要對 main 使用 git push --force。若要復原，請使用 git revert，或在功能分支上使用 git reset。」

每個章節都應遵循「用指令取代想法」的原則。代理程式會忽略「小心處理遷移」。它會遵循「執行 alembic upgrade head 前，先執行 alembic check。若出現錯誤，不要套用遷移；請詢問我。」

可直接使用的 AGENTS.md 範本（複製並調整）#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

這份範本平均有 80–120 行。如果超過 150 行，就表示應該重新整理：把部分內容移到 docs/、加上連結，或濃縮成一行。實務上，100–150 行的檔案效果最好；超過這個範圍後，品質提升開始反轉。

讓 AGENTS.md 真正有用的 5 條規則#

1. 用指令取代想法。 代理程式不理解「小心處理遷移」。它會遵循在執行 alembic upgrade head 前先執行 alembic check 的指示。代理程式處理的是指令和條件，不是情緒。所有關鍵規則都寫成「執行 X，否則執行 Y」。

2. 禁止事項要附替代方法。 單寫「不要強制推送」，代理程式收到兩三次提示後就會悄悄忽略。「不要做 X；改做 Y」這種配對才有效。範例：「不要對 main 使用 git push --force；如果需要復原，請使用 git revert 或開新的 PR。」

3. 只設一個真實資訊來源。 根目錄的 AGENTS.md 是整個專案的真實資訊來源。如果是 monorepo，就在子資料夾中使用巢狀 AGENTS.md，遵循「最近的檔案優先」規則。不要並列放置互相矛盾的檔案。

4. 可驗證的「完成」標準。 「測試必須通過」毫無用處。精確標準是：npm test 傳回結束代碼 0，且標準輸出中沒有 FAIL。「程式碼應該整潔」也毫無用處。精確標準是：npm run lint 成功完成且沒有警告。只有明確寫出條件，代理程式才知道「完成」代表什麼。

5. 檔案少於 150 行。 超過 150 行後，指標就開始惡化：代理程式需要花更多上下文閱讀，因而漏掉重要規則。如果內容太多，就把細節移到 docs/architecture.md，並從 AGENTS.md 連結過去，只在檔案中保留指令和界線。

讓 AGENTS.md 變成垃圾的 10 種錯誤#

1. 沒有指令的模糊規則。 代理程式會忽略「小心處理遷移」——這句話對它毫無意義。只有具體指令和條件才有效：「執行 alembic upgrade head 前，先執行 alembic check。如果有錯誤，不要套用遷移；請詢問我。」

2. 「整潔的程式碼」。 這句話沒有用。請換成具體模式：「使用搭配 hooks 的函式元件。範例：function LoginForm() { const [email, setEmail] = useState(''); ... }」

3. 缺乏結構的散文。 如果 AGENTS.md 有 300 行散文卻沒有標題，代理程式會花費 80K 個上下文 token 閱讀無關段落，並漏掉重要內容。請使用 H2／H3 標題、簡短章節和項目符號清單。

4. 超過 150 行的檔案。 超過這個門檻後，品質指標就會下降。請拆成主檔案，再連結到 docs/ 中的詳細說明。

5. 30 項以上沒有替代方法的禁令。 如果檔案只列出一長串「不要做 X，不要做 Y」，卻沒有解釋「改做 Z」，代理程式就只能盲目摸索。

6. 重複 README.md。 如果 README 已經寫了「如何安裝和執行」，就不要複製到 AGENTS.md。請改為用一行指向 README，並在 AGENTS.md 中說明代理程式需要、人類貢獻者卻不需要的資訊。

7. 硬編碼密鑰。 AGENTS.md 可能是公開的（因為它放在 Git 中）。不要寫入真實 API 金鑰、token 或密碼。只要指向密鑰存放位置即可：「請查看 Vault：secret/staging/db。」

8. 優先順序互相衝突卻未排序。 「快速交付」和「維持 90% 測試涵蓋率」並列時，代理程式不知道該選哪一個。請明確排序：「先確保測試涵蓋率 ≥80%，再求速度。兩者衝突時，以測試為優先。」

9. 過時文件。 架構說明寫著 REST + polling，但實際上早已改成 WebSockets。代理程式照著過時說明做，就會破壞架構。規則：架構變更時，必須在同一個 PR 中更新 AGENTS.md。

10. 為簡單任務加入過度複雜的架構說明。 如果任務只是修改設定檔中的兩行，代理程式不需要閱讀 14 個微服務的完整拓樸。把「深入」的架構說明移到 docs/architecture.md；AGENTS.md 只需保留「若任務涉及架構，請閱讀 docs/architecture.md。」

GitHub Blog 對超過 2,500 個 AGENTS.md 儲存庫的研究指出了主要結論：

「大多數代理程式檔案都因為內容太籠統而失敗。『你是一位樂於助人的程式碼助理』這種指示行不通。」

（GitHub Blog，由英文翻譯）

如何在同一個儲存庫中保留 AGENTS.md 和 CLAUDE.md？#

實務上的主要問題是，如何在不重複內容的情況下共存兩個檔案。有三種情況：

情況 1：只使用 Claude Code。 保留 CLAUDE.md，並使用 Claude Code 的所有功能：使用 ~/.claude/CLAUDE.md 放置使用者層級指示、CLAUDE.md 放置專案指示、CLAUDE.local.md 放置個人覆寫規則、@import 匯入其他檔案，以及 .claude/skills/ 放置專用技能。不需要 AGENTS.md。

情況 2：使用多個程式設計用戶端。 將共通規則放在 AGENTS.md，再逐一設定並驗證每個用戶端。Gemini CLI 可設定上下文檔名，Aider 則可透過 read 設定載入檔案。這些是明確的載入途徑，不是相同的自動尋找機制。

在無害的測試儲存庫開啟新工作階段，加入獨特且無害的指示，例如「在測試回覆中加入 instructions-loaded 標記」。除了回覆，也要檢查用戶端官方提供的已載入檔案檢視或日誌。針對實際使用的每個用戶端與版本重複檢查。模型聲稱讀過檔案，不是獨立的載入證據；一次成功也不能證明其他所有工具都支援。

情況 3：混合團隊（Claude Code + 其他工具）。 這是 2026 年最常見的配置。解決方法是以 AGENTS.md 作為主要檔案。如果沒有 Claude Code 專用規則，就不要建立 CLAUDE.md：自 2.1.277 版起，只要專案中沒有 CLAUDE.md，Claude Code 就會讀取 AGENTS.md。如果有這類規則，則將 CLAUDE.md 設為符號連結，或建立一個匯入 @AGENTS.md 的簡短包裝檔。

修改前先檢查並備份兩檔。都存在時，將不衝突共通規則合入 AGENTS.md，Claude 特定指示留在 CLAUDE.md 並以 @AGENTS.md 匯入，保留既有符號連結。

只有 AGENTS.md 不存在、CLAUDE.md 是一般檔時，才用以下 macOS／Linux 防護，拒絕覆蓋既有目標或符號連結：

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

更名成功後，CLAUDE.md 是指向 AGENTS.md 的符號連結。所有讀取 AGENTS.md 的代理程式都會看到相同內容。Claude Code 讀取 CLAUDE.md 時，也會透過符號連結看到相同內容。

在 Windows 上，建立符號連結需要開啟開發人員模式（或使用管理員權限），對整個團隊而言可能不太方便。替代方法是建立一個透過匯入讀取 AGENTS.md 的簡短 CLAUDE.md：

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

在 Claude Code 中，這種語法只需一行就能載入 AGENTS.md，並在下面加入 Claude Code 專用的補充事項。如果之後想移除 AGENTS.md，只要刪除匯入行即可。根據 Claude Code 文件，即使它能自行讀取 AGENTS.md，也不會重複載入同一個檔案。

2026 年多工具團隊的標準配置：

repo-root/
├── AGENTS.md                              # 真實資訊來源，≤150 行
├── CLAUDE.md                              # 只有在有 Claude 專用規則時才需要：符號連結 → AGENTS.md，或 @AGENTS.md + 補充規則
├── .cursor/rules/                         # Cursor 專用的指定規則
├── .github/copilot-instructions.md        # 如有使用，寫上「請參閱 AGENTS.md」
└── docs/architecture.md                   # AGENTS.md 所參照的詳細架構文件

關於 CLAUDE.md 的更多資訊，請閱讀指南「如何正確設定 CLAUDE.md」。關於代理程式為何需要大型指示檔案，請閱讀「什麼是情境工程」。

2026 年有什麼變化？AAIF 為何將 AGENTS.md 納入 Linux Foundation？#

2026 年 5 月 AI 程式碼領域的主要政治動態，不是另一款模型問世，而是格式開始整合。過去每家廠商都有自己的規則檔案，這對廠商很方便，對使用多種工具的團隊卻很麻煩。

在 2025 年 12 月 9 日的新聞稿中，Linux Foundation 宣布成立 Agentic AI Foundation，並將三種格式納入旗下：

• AGENTS.md（OpenAI）— 代理程式的指示檔案格式
• Model Context Protocol（MCP）（Anthropic）— 將外部工具連接到代理程式的通訊協定
• goose（Block）— 開放原始碼代理程式架構

摘自 Linux Foundation 新聞稿：

「將這些專案整合到 AAIF 旗下，能確保它們在只有開放治理才能提供的透明度與穩定性中發展。」

（Linux Foundation 新聞稿，2025 年 12 月 9 日，由英文翻譯）

到了 2026 年 2 月 24 日，已有 146 個組織加入 AAIF（兩個月內新增 97 個成員）。新加入的 Gold 成員包括 Red Hat、ServiceNow、Akamai、Lenovo、JPMorgan Chase、Huawei、Hitachi、UiPath、American Express 和 Autodesk。Anthropic 是推動 MCP 的 Platinum 級成員。OpenAI 是推動 AGENTS.md 的 Platinum 級成員。Block 是支持 goose 的 Platinum 級成員。

這改變了 AGENTS.md 的定位：它從「OpenAI 的格式」轉變為業界標準。2026 年春季，Claude Code 尚未加入；到了 9 月，隨著 2.1.277 版推出，它學會自行讀取 AGENTS.md。CLAUDE.md 並未消失，只要專案中有這個檔案，預設仍由它優先。

實用起點是將共通專案規則放在 AGENTS.md，再搭配各用戶端需要的匯入、包裝檔或明確讀取設定。Claude Code 應先確認安裝版本及指示檔優先順序，再決定是否需要 CLAUDE.md 匯入或符號連結。每個用戶端都需驗證載入；本文並未建立任何涵蓋百分比。

接下來#

AGENTS.md 是「如何與代理程式達成共識，讓它能可靠運作」的第一個基礎要素。接著是第二個要素——專案的知識資料夾，內含商業背景、受眾、產品和價格。第三個要素是情境工程，負責串起一切：代理程式在每個步驟會看到哪些檔案、如何在不同工作階段之間保留狀態，以及如何切換不同模型。

實用資料：Ailoot 文件。

更多資料與工具：Ailoot。