# AGENTS.md 是什麼？如何在 30 分鐘內撰寫自己的檔案 > AGENTS.md 格式、AI 工具支援、即用範本、規則與常見錯誤。如何讓 AGENTS.md 與 CLAUDE.md 及其他指示檔案協同運作。 Source: https://ailoot.ai/blog/zh-hant-tw/agents-md-guide-template/ Canonical: https://ailoot.ai/blog/zh-hant-tw/agents-md-guide-template/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-034 Revision: sha256-e095e542fbf84817bb93b05ccc507ed4e29534ea9647d231317636ce19bfa986 關於氛圍編碼與使用代理程式的實用資料：[Ailoot 文件](https://ailoot.ai/docs/)。 ## 用一段話認識 AGENTS.md
重點摘要 AGENTS.md 是放在專案根目錄的純 Markdown 檔案，內含給 AI 代理程式的指示：如何安裝相依套件、如何執行測試、應遵循哪種程式碼風格，以及哪些內容不可碰。這是一種開放格式，由 OpenAI 於 2025 年 8 月建立，並於同年 12 月加入 Linux Foundation。許多程式設計工具可以使用它，但載入方式會隨用戶端與版本而異：有些會自動尋找 AGENTS.md，其他則需要明確設定檔名或讀取檔案。自 2.1.277 版（2026 年 9 月）起，如果專案中沒有 CLAUDE.md，Claude Code 也會讀取 AGENTS.md。如果有 CLAUDE.md，Claude Code 預設只會讀取該檔案；可透過加入 `@AGENTS.md` 這一行或建立符號連結來納入 AGENTS.md。
以下將參考 [agents.md](https://agents.md)、[OpenAI Codex](https://github.com/openai/codex) 文件、[JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html)、[Cursor Rules Docs](https://cursor.com/docs/rules)、[GitHub Copilot Coding Agent 變更日誌](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)，以及 [Linux Foundation 關於 Agentic AI Foundation 的新聞稿](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)來說明這種格式。所有數據與功能截至 2026 年 5 月 30 日；Claude Code 對 AGENTS.md 的支援則依據 [Anthropic 文件](https://code.claude.com/docs/en/memory#agents-md)，並納入 2026 年 9 月 24 日的更新。 如果你不了解市面上這一大群工具是什麼，也不知道為什麼它們需要共用檔案，請先閱讀指南[「2026 年用什麼來寫程式：從 Claude Code 到 Antigravity 的 8 種 AI 工具」](https://ailoot.ai/blog/zh-hant-tw/ai-coding-tools/)。本文專門介紹 AGENTS.md 格式，以及如何在 30 分鐘內撰寫自己的檔案。 ## AGENTS.md 是什麼？它從何而來？
重點摘要 AGENTS.md 是一種開放的 Markdown 檔案格式，可由你自行撰寫給 AI 代理程式的指示。OpenAI 於 2025 年 8 月隨 Codex CLI 一同發布這項格式，並立即邀請 Cursor、Sourcegraph Amp、Google Jules 和 Factory 成為共同作者。概念很簡單：「不要為每種工具各自建立專有檔案；讓我們一起採用一種格式。」2025 年 12 月 9 日，AGENTS.md 與 Anthropic 的 MCP、Block 的 goose 一同加入 Linux Foundation，成為新成立的 Agentic AI Foundation 三個創始專案之一。到了同年 12 月，已有超過 60,000 個 GitHub 儲存庫在根目錄中放置 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](https://agents.md)。網站上寫道： > 「把 AGENTS.md 想成是給代理程式看的 README。」 > > （[agents.md](https://agents.md)，由英文翻譯） 重點是，AGENTS.md 是 README 的補充。README 是寫給人看的：「專案是什麼、如何在本機執行、如何參與貢獻。」AGENTS.md 則是寫給代理程式看的：精確的 Shell 指令、可驗證的「完成」標準，以及「絕對不要碰這裡」之類的界線。 網站上寫道： > 「AGENTS.md 是 README 的補充：它記錄代理程式需要的額外資訊，有時甚至是詳細資訊，例如建置步驟、測試和慣例。這些內容放在 README 會顯得雜亂，或根本不是人類貢獻者所需的資訊。」 > > （[agents.md](https://agents.md)，由英文翻譯） 到了 2025 年 9 月，GitHub Copilot Coding Agent 已支援這種格式（[變更日誌，2025 年 8 月 28 日](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)）。到了 12 月，Cursor、Junie、Gemini CLI、Aider 等十多種工具也加入了。2025 年 12 月 9 日，Linux Foundation 成立了 [Agentic AI Foundation（AAIF）](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)：三個創始專案分別是 OpenAI 的 AGENTS.md、Anthropic 的 MCP，以及 Block 的 goose。創始成員包括 AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft 和 OpenAI。到了 2026 年 2 月 24 日，基金會已納入[146 個組織](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members)，包括 Red Hat、ServiceNow、Akamai、Lenovo、JPMorgan Chase、Huawei、UiPath 和 Hitachi。 從那時起，AGENTS.md 就不再是「又一個 OpenAI 的東西」，而成為事實上的標準。 ## 哪些 AI 代理程式會讀取 AGENTS.md？哪些不會？
重點摘要 AGENTS.md 已用於許多程式設計工具，包括下表列出的用戶端。這份表格說明的是載入途徑，並不保證原生支援完全相同：自動尋找、明確設定、檔名優先順序，以及巢狀檔案的處理都可能不同。Anthropic 的 Claude Code 長期是例外：要求支援的 issue \#6235 從 2025 年 8 月到 2026 年 8 月一直保持開啟。自 2.1.277 版（2026 年 9 月 18 日）起，如果專案沒有 CLAUDE.md，Claude Code 會自行讀取 AGENTS.md。如果有 CLAUDE.md，預設只會讀取該檔案；可在 CLAUDE.md 中加入 `@AGENTS.md` 這一行，或透過符號連結納入 AGENTS.md。
截至 2026 年 5 月 30 日的支援狀況；Claude Code 一列於 2026 年 9 月 24 日更新： | 工具 | 是否讀取 AGENTS.md | 日期／來源 | |----|----|----| | OpenAI Codex CLI | 是（原生格式） | 2025 年 8 月，[agents.md](https://agents.md) | | GitHub Copilot Coding Agent | 是 | 2025 年 8 月 28 日，[GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) | | Cursor | 是，根目錄與巢狀目錄 | [Cursor Rules Docs](https://cursor.com/docs/rules) | | JetBrains Junie | 是，專案與全域 `~/.junie/AGENTS.md` | [Junie Docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) | | Gemini CLI（Google） | 是，透過 `.gemini/settings.json` 設定 `fileName: AGENTS.md` | [agents.md](https://agents.md) | | Jules（Google） | 是，標準的共同作者 | 2025 年 8 月 | | Sourcegraph Amp | 是，標準的共同作者 | 2025 年 8 月 | | Aider | 是，透過 `.aider.conf.yml` 中的 `read: AGENTS.md` | [agents.md](https://agents.md) | | Factory | 是，標準的共同作者 | 2025 年 8 月 | | OpenCode | 是 | — | | Zed | 是 | [agents.md](https://agents.md) | | Warp | 是 | [agents.md](https://agents.md) | | VS Code | 是 | [agents.md](https://agents.md) | | Windsurf | 是 | — | | Devin（Cognition） | 是，透過 Spec Kit Skills | 2026 年 4 月 | | RooCode、Kilo Code、Augment Code | 是 | [agents.md](https://agents.md) | | **Claude Code（Anthropic）** | **是，前提是專案沒有 CLAUDE.md** | 自 2.1.277 版起（2026 年 9 月 18 日），[Claude Code 文件](https://code.claude.com/docs/en/memory#agents-md) | 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。根據[文件](https://code.claude.com/docs/en/memory#agents-md)，運作方式如下： | 專案中的檔案 | Claude Code 讀取的內容 | |----|----| | 只有 AGENTS.md | AGENTS.md | | AGENTS.md 和 CLAUDE.md（或 CLAUDE.local.md） | 只有 CLAUDE.md | | 含有 `@AGENTS.md` 這一行的 CLAUDE.md | 納入 AGENTS.md 的 CLAUDE.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` 有什麼不同？
重點摘要 從技術上說，它們沒有什麼特別之處：四種格式（AGENTS.md、CLAUDE.md、`.cursorrules`、`.github/copilot-instructions.md`）都是附有代理程式指示的一般 Markdown 檔案。差異在於哪些工具會讀取它們，以及它們放在哪裡。可將多個用戶端的共通指示放在 AGENTS.md，並另外管理各用戶端的尋找方式或設定。CLAUDE.md 只供 Claude Code 使用，但可使用進階功能：依路徑套用規則、用 `CLAUDE.local.md` 覆寫個人設定、用 `@import` 引入其他檔案，以及專案、使用者、個人檔案的階層。`.cursorrules` 在 Cursor 中已過時；新的系統使用 `.cursor/rules/*.mdc`，並依檔案類型自動附加規則。`.github/copilot-instructions.md` 只供網頁版 Copilot 使用。
截至 2026 年 5 月 30 日的四種格式比較： | 格式 | 讀取者 | 放置位置 | 優點 | 缺點 | |----|----|----|----|----| | **AGENTS.md** | 多種工具；尋找或設定途徑需逐一確認 | 儲存庫根目錄及用戶端支援的巢狀子資料夾 | 可用一份檔案管理共通指示，再搭配各用戶端載入設定。不依賴單一廠商 | 載入、優先順序與階層處理需依用戶端確認 | | **CLAUDE.md** | 只有 Claude Code | 根目錄 + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | 階層結構、依路徑套用規則、`@import`、技能、hooks | 只有 Claude 能用。在 Cursor／Codex／Copilot 中無法使用 | | **`.cursor/rules/*.mdc`** | 只有 Cursor | `.cursor/rules/.mdc` | 可依檔案類型（TS、Python、特定路徑）自動附加 | 只有 Cursor 能用，使用非標準的 `.mdc` 語法 | | **`.github/copilot-instructions.md`** | GitHub Copilot（網頁版與傳統版） | `.github/` | 可直接在 GitHub.com 的瀏覽器中運作 | 只有 Copilot 能用，且與 AGENTS.md 內容重複 | AGENTS.md 可放共通專案指示，但每個用戶端的載入途徑及個人設定仍需分別設定。Claude Code 可用 `CLAUDE.local.md`，Cursor 則有使用者層級的本機 `.mdc` 檔案。AGENTS.md 本身不提供這項功能；你需要搭配其他檔案，或與團隊約定把個人規則寫在會被 gitignore 的區段中。 另一個重要細節是 monorepo。Codex 和 Cursor 採用「最近的 AGENTS.md 優先」這項規則： > 「在 monorepo 中，請在每個套件內放置個別的 AGENTS.md。代理程式會自動讀取目錄樹中最近的檔案，並以最近的檔案為準。」 > > （[agents.md](https://agents.md)，由英文翻譯） [agents.md](https://agents.md) 提到，OpenAI 的主要 monorepo 有 88 個 AGENTS.md，分別供不同子套件使用。如果你在 monorepo 中工作，請將規則分層：根目錄放一般規則，子資料夾放特定規則。 ## 好的 AGENTS.md 應該包含什麼？
重點摘要 好的 AGENTS.md 大綱包含 8 個常見章節：專案概覽、設定指令、程式碼風格、開發環境提示、測試指示、PR 規範、安全注意事項，以及界線（不可做的事）。其他內容都是選擇性的。主要原則是每個項目都必須是精確指令或具體範例，而不是「撰寫整潔的程式碼」之類的一般想法。
[agents.md](https://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 範本（複製並調整）
重點摘要 以下是一般 Web 專案的 AGENTS.md 起始範本。將它複製到儲存庫根目錄，替換 ``、`` 和精確指令，並移除不需要的章節。調整約需 20–30 分鐘；如果是第一次撰寫，可能需要更久。
````markdown # AGENTS.md ## Project overview - . Stack: . Main entities: . 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: `(): ` (`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 條規則
重點摘要 好的 AGENTS.md 遵循五條規則：用指令取代想法、禁止事項要附替代方法、只設一個真實資訊來源、訂定可驗證的完成標準，以及將檔案控制在 150 行以下。
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 種錯誤
重點摘要 AGENTS.md 無法發揮作用，主要是因為措辭含糊。GitHub Blog 在一項涵蓋超過 2,500 個儲存庫的研究中指出，多數檔案因為寫得太籠統而失敗。例如，「你是一位樂於助人的程式碼助理」對代理程式完全沒有提供有用資訊。以下列出 10 種常見錯誤，以及它們在不良檔案中的表現：重複 README、缺乏結構的散文、30 項以上沒有替代方法的禁令、優先順序互相衝突、硬編碼密鑰、過時文件，以及為簡單任務加入過度複雜的架構說明。
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 儲存庫的研究](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)指出了主要結論： > 「大多數代理程式檔案都因為內容太籠統而失敗。『你是一位樂於助人的程式碼助理』這種指示行不通。」 > > （[GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)，由英文翻譯） ## 如何在同一個儲存庫中保留 AGENTS.md 和 CLAUDE.md？
重點摘要 有三種情況：（1）只使用 Claude Code——保留 CLAUDE.md，不需要 AGENTS.md。（2）只使用非 Claude 工具（Codex、Cursor、Copilot、Junie）——以 AGENTS.md 作為唯一的真實資訊來源。（3）Claude Code 與其他工具混合使用的團隊——以 AGENTS.md 作為主要檔案。如果沒有 Claude 專用規則，可以省略 CLAUDE.md：自 2.1.277 版起，Claude Code 會自行讀取 AGENTS.md。如果有個別規則，則透過符號連結或 `@AGENTS.md` 匯入，將 AGENTS.md 連接到 CLAUDE.md。macOS／Linux 只有在 AGENTS.md 不存在時才更名。兩檔都在就先保存合併，再以含 `@AGENTS.md` 的簡短 CLAUDE.md 包裝，絕不可覆蓋既有 AGENTS.md。在 Windows 上，符號連結需要開啟開發人員模式，因此使用匯入方式更簡單。
實務上的主要問題是，如何在不重複內容的情況下共存兩個檔案。有三種情況： **情況 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 設定載入檔案。這些是明確的載入途徑，不是相同的自動尋找機制。 | 載入途徑 | 應驗證的項目 | |----|----| | 自動尋找 AGENTS.md | 已安裝用戶端官方說明的根目錄、巢狀檔案及優先順序規則 | | Gemini CLI 或 Aider 等明確設定 | 設定的檔名或 read 路徑，以及用戶端的已載入上下文檢視 | | Claude Code 條件式載入或匯入 | 安裝版本與檔案優先順序，請見[獨立的 Claude Code AGENTS.md 指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-agents-md-support/) | 在無害的測試儲存庫開啟新工作階段，加入獨特且無害的指示，例如「在測試回覆中加入 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 防護，拒絕覆蓋既有目標或符號連結： ```bash 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： ```markdown # 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」](https://ailoot.ai/blog/zh-hant-tw/claude-md-template/)。關於代理程式為何需要大型指示檔案，請閱讀[「什麼是情境工程」](https://ailoot.ai/blog/zh-hant-tw/context-engineering/)。 ## 2026 年有什麼變化？AAIF 為何將 AGENTS.md 納入 Linux Foundation？
重點摘要 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 個組織。這表示 AGENTS.md 不再只是「OpenAI 的東西」，而是與 MCP 並列的業界標準。實務上，如果你正在打造能與不同廠商代理程式搭配使用的產品，將 AGENTS.md 放在根目錄是基本功。否則你得維護三、四份平行檔案，不到一個月就會出現差異。
2026 年 5 月 AI 程式碼領域的主要政治動態，不是另一款模型問世，而是格式開始整合。過去每家廠商都有自己的規則檔案，這對廠商很方便，對使用多種工具的團隊卻很麻煩。 在 [2025 年 12 月 9 日的新聞稿](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)中，Linux Foundation 宣布成立 Agentic AI Foundation，並將三種格式納入旗下： - **AGENTS.md**（OpenAI）— 代理程式的指示檔案格式 - **Model Context Protocol（MCP）**（Anthropic）— 將外部工具連接到代理程式的通訊協定 - **goose**（Block）— 開放原始碼代理程式架構 摘自 Linux Foundation 新聞稿： > 「將這些專案整合到 AAIF 旗下，能確保它們在只有開放治理才能提供的透明度與穩定性中發展。」 > > （[Linux Foundation 新聞稿，2025 年 12 月 9 日](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation)，由英文翻譯） 到了 2026 年 2 月 24 日，[已有 146 個組織加入 AAIF](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members)（兩個月內新增 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 是「如何與代理程式達成共識，讓它能可靠運作」的第一個基礎要素。接著是第二個要素——專案的知識資料夾，內含商業背景、受眾、產品和價格。第三個要素是[情境工程](https://ailoot.ai/blog/zh-hant-tw/context-engineering/)，負責串起一切：代理程式在每個步驟會看到哪些檔案、如何在不同工作階段之間保留狀態，以及如何切換不同模型。 實用資料：[Ailoot 文件](https://ailoot.ai/docs/)。
### 來源 - [agents.md — 標準官方網站](https://agents.md) - [Linux Foundation：成立 Agentic AI Foundation（2025 年 12 月 9 日）](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) - [AAIF 歡迎 97 個新成員加入（2026 年 2 月 24 日）](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) - [OpenAI 共同創立 Agentic AI Foundation](https://openai.com/index/agentic-ai-foundation/) - [GitHub Changelog：Copilot coding agent 支援 AGENTS.md（2025 年 8 月 28 日）](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) - [GitHub Blog：來自 2500 多個 AGENTS.md 儲存庫的經驗](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) - [Claude Code 文件：Claude 如何讀取 AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - [JetBrains Junie 指南文件](https://junie.jetbrains.com/docs/guidelines-and-memory.html) - [Cursor Rules Docs](https://cursor.com/docs/rules)
更多資料與工具：[Ailoot](https://ailoot.ai/)。 ## 常見問題：AGENTS.md 是什麼？如何在 30 分鐘內撰寫自己的檔案 | Ailoot ### AGENTS.md 與 CLAUDE.md 都存在時怎麼辦？ 先備份比對，將共通規則合入 AGENTS.md，Claude 特定規則留 CLAUDE.md 並加入 @AGENTS.md；不要把一個重新命名覆蓋另一個。 ### 如何讓指示可以驗證？ 寫確切設定與測試指令、預期結果及禁止變更。詳細架構移至連結文件，主指示保持易讀。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。