# 2026 年 Claude Code、Codex 和 Cursor 的單一指示檔 > 2026 年 Claude Code、Codex 和 Cursor 的單一事實來源：Claude Code 何時會自行讀取 AGENTS.md、如何將 @AGENTS.md 匯入 CLAUDE.md、符號連結，以及 /init。 Source: https://ailoot.ai/blog/zh-hant-tw/agents-md-claude-md-one-instruction-file/ Canonical: https://ailoot.ai/blog/zh-hant-tw/agents-md-claude-md-one-instruction-file/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-004 Revision: sha256-89bc7e0241b913631c996fa06bdc9b23a0cc5379a5c1c2601b951ebeae78333c 如需服務相關資訊，請參閱 [Ailoot 說明文件](https://ailoot.ai/docs/)。 ## 同時使用 Claude Code、Codex 和 Cursor 時，會有哪些改變？
重點摘要 到了 2026 年，一般 vibe coder 的設定不再只有一種工具，而是 3–5 種。Claude Code 是主要工具，Codex 用於長時間的自主任務，Cursor 則用於 IDE 中的快速編輯。每種工具都有自己的指示檔：`CLAUDE.md`、`AGENTS.md`、`.cursorrules`。如果靠手動同步，每次都得在五個地方修改同一行，還會忘記更新 Cursor；一週後，Claude 和 Codex 就會對同一個提示給出不同結果。
在本文的例子中，Claude Code 是主要工具，而 Codex 和 Cursor 用於特定任務。我的 `CLAUDE.md` 約有 250 行指示：要依什麼順序讀取哪些內容、哪些內容不得動、部署時要用哪些指令，以及提交格式規則。我第一次在這個專案嘗試 Codex CLI 時，它完全不知道這些規則：它執行了 `git push --force`、翻查 `.env`，還不小心重新命名了檔案。 我一開始手動把 `CLAUDE.md` 複製成 `AGENTS.md`。兩週後，我發現專案裡已經有四個版本的相同指示：`CLAUDE.md`、`AGENTS.md`、`.cursorrules` 和 `.windsurf/rules/`。它們各自有些差異。這不是 Claude 或 Cursor 的問題，而是任何有多個事實來源的系統都會遇到的基本陷阱。我在[多代理工作指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-codex-together/)中更詳細地討論了這個問題。 2026 年 6 月，Anthropic 的 Claude Code 記憶說明文件提出了一個解法：共用檔案加上匯入。自 2026 年 9 月起，如果專案沒有 `CLAUDE.md`，Claude Code 就會自行讀取 `AGENTS.md`；如果有 Claude 專用規則，則需要匯入。下文將說明何時只用一個 `AGENTS.md` 就足夠、如何設定匯入，以及如何區分共用規則和 Claude 專用規則。 ## Claude Code 會自行讀取 AGENTS.md 嗎？
重點摘要 會，從 2026 年 9 月 18 日發布的 2.1.277 版開始，但前提是工作目錄或其上層都沒有 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`。如果存在 `CLAUDE.md`，Claude Code 預設只會讀取該檔案；你可以在 `CLAUDE.md` 中加入 `@AGENTS.md` 這一行，或使用符號連結來納入 `AGENTS.md`。你可以在 `/config` 的「Project instructions」中變更行為。9 月以前的 Claude Code 完全不會讀取 `AGENTS.md`，當時唯一的方法就是匯入。
在 2026 年 9 月以前，答案是「不會」。要求支援 AGENTS.md 的 Issue #6235 自 2025 年 8 月起一直處於開啟狀態，並於 2026 年 8 月 17 日關閉。在此期間，記憶說明文件一直指出同一個解法：建立 `CLAUDE.md`，並將 `AGENTS.md` 作為匯入內容納入其中。從 2.1.277 版開始，說明文件的說法改變了：

Claude Code 可以將 AGENTS.md 作為專案指示讀取，因此已為其他代理設定好的儲存庫，不需要 CLAUDE.md、匯入或設定也能運作。

— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Claude Code 讀取的內容，取決於專案中有哪些檔案： | 專案中的檔案 | Claude Code 讀取的內容 | |----|----| | 有 `AGENTS.md`，且工作目錄或其上層沒有 `CLAUDE.md` 或 `CLAUDE.local.md` | `AGENTS.md` | | 工作目錄或其上層有 `AGENTS.md` 和 `CLAUDE.md`（或 `CLAUDE.local.md`） | 只有 `CLAUDE.md` | | `CLAUDE.md` 中有 `@AGENTS.md` 這一行 | `CLAUDE.md`，以及透過匯入納入其中的 `AGENTS.md` | 這項檢查會將工作目錄及其上層目錄中的 `CLAUDE.md`、`.claude/CLAUDE.md` 和 `CLAUDE.local.md` 都算在內。個人用的 `~/.claude/CLAUDE.md`、企業管理檔案，以及 `.claude/rules/` 中的規則則不在此列：它們會與 `AGENTS.md` 一起載入。 如果沒有 `CLAUDE.md`，Claude Code 會在啟動時讀取工作目錄及其上層的所有 `AGENTS.md` 和 `.claude/AGENTS.md`；當它開啟子目錄中的檔案時，也會載入該子目錄中的 `AGENTS.md`。`AGENTS.md` 中的 `@path` 匯入也能運作。Claude Code 不會讀取 `AGENTS.local.md`、`AGENTS.override.md`，也不會讀取 `.agents/` 目錄的內容。 問題在於，個人用的 `CLAUDE.local.md` 也會列入檢查。你可能會建立這個檔案來存放未提交的規則，但 Claude Code 會因此悄悄停止讀取 `AGENTS.md`。下方的設定可解決這個問題。 你可以在 `/config` 的「Project instructions」中變更行為： | 設定 | Claude Code 讀取的內容 | |----|----| | `claude-md-or-agents-md`（預設） | `CLAUDE.md`；如果 `CLAUDE.md` 和 `CLAUDE.local.md` 都不存在，則讀取 `AGENTS.md` | | `claude-md-and-agents-md` | 兩個檔案都讀取：每個目錄先讀 `CLAUDE.md`，再讀 `AGENTS.md` | | `claude-md` | 只讀取 `CLAUDE.md` | | `managed-only` | 只讀取企業管理的 `CLAUDE.md` 和自動記憶 | 如果你想保留 `CLAUDE.local.md`，又不想失去 `AGENTS.md`，請設定 `claude-md-and-agents-md`。不會重複讀取：如果 `AGENTS.md` 已透過 `@AGENTS.md` 這一行或符號連結納入，Claude Code 就不會再載入一次，不論設定為何。 你可以用 `/memory` 指令檢查檔案是否已載入：從 2.1.280 版開始，清單中會顯示 `AGENTS.md` 的路徑。在早於 2.1.277 的版本，或停用內建 `agents-md` 外掛程式的工作階段中，Claude Code 只會讀取 `CLAUDE.md`，而且 `/config` 中不會出現「Project instructions」項目。在 2.1.281 版以前，透過 Amazon Bedrock 的工作階段，以及停用遙測的工作階段，也會有相同情況。從舊版更新後的第一個工作階段，也可能尚未載入 `AGENTS.md`；從下一個工作階段起就會正常運作。 如果只想用一個檔案，這代表什麼？如果沒有 Claude 專用規則，可以省略 `CLAUDE.md`：`AGENTS.md` 就足夠，Claude Code、Codex 和 Cursor 都會讀取它。如果有這類規則（例如高風險目錄的 plan mode、技能、hooks），就需要 `CLAUDE.md`，而 Claude Code 會停止自行讀取 `AGENTS.md`。接著在 `CLAUDE.md` 中加入 `@AGENTS.md` 這一行，就能匯入 `AGENTS.md`；這種設定與 9 月以前的作法相同，也能支援較舊版本的 Claude Code。下文會詳細說明。 ## 如何在 CLAUDE.md 中匯入 @AGENTS.md？
重點摘要 如果專案有 `CLAUDE.md`，就需要匯入：一旦存在 `CLAUDE.md`，Claude Code 預設不會自行讀取 `AGENTS.md`。設定方法是在 `CLAUDE.md` 檔案頂端寫入 `@AGENTS.md` 這一行。Claude Code 啟動工作階段時，會將該行替換成 `AGENTS.md` 的內容，並將整份文字當作一個檔案讀取。你可以在匯入內容下方新增「Claude Code」區段，放置只適用於 Claude 的規則。匯入可使用相對路徑或絕對路徑，最多可巢狀四層。
官方說明文件中的最小可行範例如下： ```markdown @AGENTS.md ## Claude Code 在 `src/billing/` 下進行變更時，請使用 plan mode。 ``` 實際運作方式如下。第一行 `@AGENTS.md` 是匯入指示。Claude Code 在工作階段開始時解析 `CLAUDE.md`，找到這項匯入後，會在原處插入整份 `AGENTS.md` 的內容。接下來的 `## Claude Code` 標題只是 Markdown，但它會做為「Claude 專用附加規則」區段。標題下方的規則只適用於 Claude Code：在 billing 目錄中進行變更時使用 plan mode。Codex CLI 或 Cursor 不會開啟這個檔案；它們會使用一般的 `AGENTS.md`。 以下是說明文件對匯入運作方式的引述：

CLAUDE.md 檔案可以使用 @path/to/import 語法匯入其他檔案。匯入的檔案會展開，並在工作階段啟動時與引用它的 CLAUDE.md 一起載入脈絡。

— Anthropic, https://code.claude.com/docs/en/memory
幾項實用細節： - **相對路徑和絕對路徑。** `@AGENTS.md` 相對於包含匯入指示的檔案。`@/Users/me/shared/rules.md` 或 `@~/.claude/personal.md` 則是絕對路徑。我會用 `@~/.claude/personal.md` 存放不想放進儲存庫的個人偏好。 - **最多四層。** `AGENTS.md` 可以匯入 `@docs/coding-style.md`，而 `coding-style.md` 又可以匯入其他檔案，最多四層。這足以涵蓋實際所需的各種結構。 - **反引號會阻止匯入。** 如果文字寫的是 `` `@README` ``，那只是提到名稱，不會執行匯入。這很適合用來向讀者說明匯入方式，而不會意外觸發匯入。 - **匯入專案外的檔案需要核准。** 如果匯入指向工作目錄外的檔案，例如 `@~/.claude/personal.md`，Claude Code 第一次會顯示對話框，列出這些檔案。如果你拒絕，外部匯入就會停用，而且不會再次顯示對話框。專案根目錄的 `@AGENTS.md` 不會觸發對話框。這可避免意外將無關檔案載入脈絡。 在本文所述的專案中改用這種設定後，我的 `CLAUDE.md` 從 250 行縮減到 60 行：`@AGENTS.md` 加上五到七條只適用於 Claude Code 的規則（高風險目錄使用 plan mode、管理區域有哪些內容不能動，以及如何撰寫提交訊息）。所有共用內容都放在 Codex 和 Cursor 會讀取的 `AGENTS.md` 中。 ## 什麼時候該選符號連結，什麼時候該選匯入？
重點摘要 Anthropic 提供兩種方式：透過 `@AGENTS.md` 匯入，或建立符號連結 `ln -s AGENTS.md CLAUDE.md`。符號連結比較簡單——它只是別名，不需要修改檔案。但有三個缺點：Windows 需要管理員權限、無法在 `CLAUDE.md` 加入 Claude 專用規則，而且 Git 有時會在差異中把符號連結顯示成雜項。匯入是通用作法。如果沒有 Claude 專用規則，從 2.1.277 版開始兩者都不需要：Claude Code 會自行讀取 `AGENTS.md`。
說明文件中展示的符號連結方式如下： ```bash ln -s AGENTS.md CLAUDE.md ``` 接著，文件立刻針對 Windows 提出坦率的警告：

如果你或任何複製此儲存庫的人使用 Windows，請使用 @AGENTS.md 匯入。在 Windows 建立符號連結需要管理員權限或開發人員模式；如果 Git 未啟用 core.symlinks，簽出的已提交連結會變成一般文字檔，留下只有一行 CLAUDE.md，而不是該副本中的指示內容。

— Anthropic, https://code.claude.com/docs/en/memory
比較表： | 條件 | `@AGENTS.md` 匯入 | `ln -s` 符號連結 | |----|----|----| | **在 Windows 上不需管理員權限即可使用** | 可以 | 不行（需要開發人員模式） | | **可加入 Claude 專用規則** | 可以，放在匯入內容下方 | 不行，檔案完全相同 | | **在 Git 中顯示為一般 Markdown** | 可以 | 顯示為連結（取決於 `core.symlinks`） | | **可匯入多個檔案** | 可以，最多四層 | 不行，一對一 | | **Claude Code 中的快取／失效處理** | CLAUDE.md 的標準作法 | 可運作，但符號連結有一些不易察覺的陷阱 | | **預設選擇** | 適合所有人 | 只有在不需考慮跨平台使用時才適用 | 本文所述的專案使用匯入，理由如下： 1. **團隊使用的作業系統混雜。** 我用 Mac；本文例子中的團隊約有一半使用 Windows，另一半使用 Mac。如果儲存庫中有符號連結，沒有開啟開發人員模式的 Windows 使用者簽出後，會得到一個只包含 `AGENTS.md` 單行文字的一般檔案。這會造成奇怪的錯誤：有時規則有效，有時無效，原因也不清楚。 2. **我需要 Claude 專用規則。** 在 `@AGENTS.md` 下方，我的 `CLAUDE.md` 有一個「Claude Code」區段，其中包含以下規則：架構任務使用 `--effort high`、執行 `git push` 前先執行 `npm run build`，以及不要手動呼叫 `/api/v1/deploy`。Codex 不理解這些指令。 3. **比較容易偵錯。** 發生問題時，我打開 `CLAUDE.md` 就能看到匯入內容和覆寫規則。符號連結沒有標示「這些內容是在此新增的」。如需了解 Claude Code 設定的偵錯方法，請參閱[安全模式指南](https://ailoot.ai/blog/zh-hant-tw/claude-code-safe-mode-recovery/)。 如果沒有 Claude 專用規則，從 2.1.277 版開始就不再需要符號連結：刪除 `CLAUDE.md`，Claude Code 便會自行讀取 `AGENTS.md`。只有在團隊中有人使用舊於 2.1.277 的版本，而且無法更新時，才保留符號連結。如果有 Claude 專用規則，十之八九使用匯入會更方便。 ## Codex、Cursor、Copilot、Windsurf 和 Gemini CLI 會讀取什麼？
重點摘要 每種工具都會讀取自己的檔案，有時會讀取不只一個。Claude Code 會讀取 `CLAUDE.md`，從 2026 年 9 月起，如果專案沒有 `CLAUDE.md`，也會讀取 `AGENTS.md`。Codex CLI 會讀取 `AGENTS.md` 和 `AGENTS.override.md`。Cursor 會讀取舊版 `.cursorrules` 格式或新版 `.cursor/rules/*.mdc`，而且從 2026 年夏季起也會讀取 `AGENTS.md`。Copilot 會讀取 `.github/copilot-instructions.md` 或 `.github/instructions/*.instructions.md`。Windsurf 會讀取舊版 `.windsurfrules` 或新版 `.windsurf/rules/`。Gemini CLI 會讀取 `GEMINI.md`。Aider 和 Cline 已經採用 `AGENTS.md`。
以下是七種主要工具的對照表（根據各工具的官方說明文件）： | 工具 | 主要指示檔 | 其他選項 | 會讀取 AGENTS.md 嗎？ | |----|----|----|----| | **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`、`./.claude/CLAUDE.md`、管理政策 | 會，若專案沒有 `CLAUDE.md`（自 2.1.277 起）；否則透過匯入讀取 | | **Codex CLI**（OpenAI） | `AGENTS.md` | `AGENTS.override.md` | 會（原生支援） | | **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules`（已棄用） | 會 | | **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | 透過擴充功能 | | **Windsurf** | `.windsurf/rules/` | `.windsurfrules`（已棄用） | 會 | | **Gemini CLI** | `GEMINI.md` | \- | 不會 | | **Aider、Cline、opencode** | `AGENTS.md` | \- | 會（原生支援） | 這代表什麼？如果儲存庫中有 `AGENTS.md`，而且在需要 Claude 專用規則時有包含匯入的 `CLAUDE.md`，七種工具中有五種會自動取得最新指示。Cursor 和 Windsurf 各自有原生檔案，可以維持現狀（它們也會讀取 `AGENTS.md`），也可以加入 `@AGENTS.md` 匯入；不過兩者的語法不同，而且不一定都支援。 新專案最簡單的策略如下： 1. **將所有共用規則放進 `AGENTS.md`**——95% 的規則都屬於此處。 2. **需要 Claude 專用規則時才建立 `CLAUDE.md`：** 第一行放 `@AGENTS.md`，再於下方新增 Claude 專用規則。如果沒有這類規則，`CLAUDE.md` 就沒有必要；從 2.1.277 版開始，Claude Code 會自行讀取 `AGENTS.md`。 3. **為 Cursor 保留 `.cursor/rules/`**，以便在少數需要 Cursor 專屬功能時使用（例如 `@Codebase` 和 `@Docs` 指令）。 4. **Windsurf 也採用相同做法：** 不再使用舊的 `.windsurfrules`；只有需要符合其語法的模式時才使用新版 `.windsurf/rules/`。 這種方式只需投入 20% 的工夫，就能得到 80% 的好處。以我的經驗，在「Antigravity」整理混合團隊的環境時，超過兩個事實來源（共用規則和 Claude 專用規則）就會變得難以維護。如果有人在 `.cursorrules` 中新增規則，卻忘了更新 `AGENTS.md`，一週後 Cursor 和 Codex 就會彼此不一致。 ## Claude Code 的 /init 如何採用現有的 AGENTS.md？
重點摘要 `/init` 會根據儲存庫中已有的內容建立 `CLAUDE.md`，省下 20–30 分鐘的手動工作。預設情況下，它會採用 Cursor 規則（`.cursor/rules/`、`.cursorrules`）和 Copilot 規則（`.github/copilot-instructions.md`）；在 `CLAUDE_CODE_NEW_INIT=1` 模式下，則會讀取 `AGENTS.md`、`.windsurfrules` 和 `.clinerules`。此模式也會啟動互動式多階段流程：它會提問、透過子代理探索程式碼，並在寫入前提出計畫。自 2026 年 9 月起，如果專案中已有 `AGENTS.md`，`/init` 會帶來一項缺點：新建的 `CLAUDE.md` 會停用直接讀取 `AGENTS.md`，規則因此分散在兩個檔案中。
Anthropic 在說明文件中這樣描述 `/init`：

執行 /init 會讀取其他工具的指示檔，並將相關內容移至產生的 CLAUDE.md：Cursor 的規則取自 .cursor/rules/ 或 .cursorrules，Copilot 的規則取自 .github/copilot-instructions.md；若使用 CLAUDE_CODE_NEW_INIT=1，還會讀取 AGENTS.md、.devin/rules/、.windsurf/rules/ 或 .windsurfrules，以及 .clinerules。

— Anthropic, https://code.claude.com/docs/en/memory
實際上代表什麼？本文所述的儲存庫中有一份我試用 Cursor 時留下的 `.cursorrules`（約 80 行），以及一份手動整理的 `AGENTS.md`（120 行）。執行 `claude /init` 後，指令讀取了兩個檔案，去除相似規則的重複內容，並在一分鐘內整理出一份乾淨的 `CLAUDE.md`。我之後檢查並稍微編輯了一下——移除過時項目，加入標題結構。這比從頭重寫快得多。 透過環境變數啟用也會讀取 `AGENTS.md` 的互動模式： ```bash CLAUDE_CODE_NEW_INIT=1 claude ``` `/init` 啟動後，Claude 會提出一系列釐清問題：要設定哪些產出項目（`CLAUDE.md`、技能、hooks）、專案使用什麼技術堆疊，以及測試要用哪些指令。接著，子代理會探索程式碼庫——讀取 `package.json`、`README.md` 和設定檔——並補齊缺少的內容。最後會顯示一份提案，你可以在儲存前編輯。如需了解專案啟動時如何設定 Claude Code，請參閱[另一份指南](https://ailoot.ai/blog/zh-hant-tw/spec-kit-claude-code-spec-driven-development/)。 接下來談談缺點。如果專案已有一份正在使用的 `AGENTS.md`，`/init` 會在旁邊建立 `CLAUDE.md`，其中包含 `AGENTS.md` 規則的副本。從那時起，Claude Code 預設只讀取 `CLAUDE.md`，於是又有兩個事實來源：你更新 `AGENTS.md`，Claude 卻繼續使用舊副本。`/import` 指令也有類似效果：它會將 `AGENTS.md` 的單次副本附加到 `CLAUDE.md`。若要維持單一來源，請在執行 `/init` 後，將 `@AGENTS.md` 匯入放在 `CLAUDE.md` 第一行，並移除其中與 `AGENTS.md` 重複的內容。 `/init` 適合用來啟動新專案，或將專案從 Cursor 或 Copilot 移轉過來。你不必上網搜尋「最佳 CLAUDE.md 範本」——Anthropic 已經會參考儲存庫現有的內容。如果專案已有一份正在使用的 `AGENTS.md`，而且沒有 Claude 專用規則，就不需要 `/init`：Claude Code 會自行讀取 `AGENTS.md`。 ## 如何區分共用指示和 Claude 專用指示？
重點摘要 任何 AI 代理都能理解的規則都放在 `AGENTS.md`：哪些內容不能動、分支如何命名、`.env` 含有密碼，以及測試要用哪些指令。Claude Code 專用的規則則放在 `CLAUDE.md`（匯入內容下方）：plan mode、技能、hooks、技能參考資料，以及依版本區分的模型名稱。區分方式很簡單：如果規則以「Claude 應該」開頭，就放進 `CLAUDE.md`；如果以「工具應該」開頭，就放進 `AGENTS.md`。
我依照這個原則區分。放進 `AGENTS.md` 的共用規則如下： - **程式碼中哪些內容不能動。** `.env`、`node_modules`、`prisma/migrations` 資料夾（只能透過 `prisma migrate` 操作）、`.next/`、`.git/`。 - **如何命名。** 分支使用 `feat/`、`fix/`、`chore/`。提交訊息使用 `feat:`、`fix:`、`docs:` 前綴，後面加上簡短說明。元件檔案使用 `kebab-case`。 - **測試／lint 指令。** `npm run build`、`npm run lint`、`npm test`。也要說明執行 `git push` 前要先執行哪個指令。 - **架構原則。** 說明哪些內容放在 `src/lib/`、哪些放在 `src/components/`，以及商業邏輯和 UI 各自放在哪裡。 - **安全性。** 絕不提交密碼。只能透過 `prod-psql` 存取正式資料庫。只能透過 `prod` 別名使用 SSH 存取正式環境，不要使用 `root@IP`。 放在 `CLAUDE.md` 的 `@AGENTS.md` 下方的 Claude 專用規則如下： - **Plan mode。** 在高風險目錄（例如 `src/billing/`）進行變更時使用 `plan mode`。 - **Effort level。** 架構任務使用 `--effort high`，一般工作使用 `medium`。 - **技能。** 說明在什麼情況下執行哪些 AI 代理和技能。例如：「處理指南時，請執行 `build-masterskaya-guide` 技能。」 - **Claude 記憶。** 說明哪些內容要放進自動記憶，哪些要放進 `CLAUDE.local.md`。如需了解 Claude 記憶，請參閱[Memory 和 CLAUDE.md 指南](https://ailoot.ai/blog/zh-hant-tw/claude-memory-claude-md-auto-memory/)。 - **Hooks。** 如果 `.claude/settings.json` 設定了 hooks，就在 `CLAUDE.md` 中說明其用途（Codex 和 Cursor 不知道這些 hooks，也不需要知道）。 - **技能和指令。** 列出我常用的斜線指令（`/init`、`/cd`、`/memory`、`/plan`）。 界線不一定總是明確。例如，「絕不要對 `main` 執行 `git push --force`」明確屬於共用規則，因此放進 `AGENTS.md`。但「對熱分支執行 `git push` 時，先使用 plan mode」是 Claude Code 專用規則，因此放進 `CLAUDE.md`。判斷方式是：「如果我明天移除 Claude Code，只保留 Codex，這項規則是否仍然適用？」如果適用，就放進 `AGENTS.md`；如果不適用，就放進 `CLAUDE.md`。 ## AGENTS.md 應該放什麼？CLAUDE.md 或 .claude/rules 又該放什麼？
重點摘要 大型專案只靠一個 `AGENTS.md` 並不足夠：檔案會變得太龐大，每個代理也會把不必要的內容帶進脈絡。解決方法是建立 `.claude/rules/` 目錄，按主題分檔，並在 YAML 前置資訊中使用 `paths:` 設定依路徑觸發的規則。例如，只有 Claude 在 `src/api/` 工作時，API 規則才適用。這能節省大量脈絡視窗空間。Cursor 和 Windsurf 對應的做法分別是 `.cursor/rules/` 和 `.windsurf/rules/`。
如果規則超過 200 行，就該拆分了。Anthropic 的說明文件建議每個檔案以 200 行為目標，因為 `CLAUDE.md` 太長時，Claude 會開始悄悄降低遵循程度：看起來像是讀過了，實際上卻較少遵守。 以下是我認為適用於大型專案的結構： ``` my-project/ ├── AGENTS.md # 100-150 行，共用 ├── CLAUDE.md # 30-50 行：@AGENTS.md + Claude 專用 └── .claude/ ├── CLAUDE.md # 根目錄檔案的替代位置，內容相同 └── rules/ ├── api.md # 設定 paths: ['src/api/**'] ├── components.md # 設定 paths: ['src/components/**'] ├── testing.md # 不設定 paths，永遠啟用 └── security.md # 不設定 paths，永遠啟用 ``` `.claude/rules/` 中的每個檔案都可以加入以下前置資訊： ```markdown --- paths: - "src/api/**/*.ts" --- # API 規則 - 每個 endpoint 都使用 zod 驗證輸入 - 錯誤使用標準的 `{error, code}` 格式 - 必須包含 OpenAPI 註解 ``` 只有在處理符合這個模式的檔案時，Claude 才會載入這些規則。如果它修改 `src/components/Button.tsx`，API 規則就不會加入脈絡。這樣一來，脈絡視窗只會用在相關內容上。即使沒有 `CLAUDE.md`，`.claude/rules/` 目錄也能運作：如果專案只有 `AGENTS.md`，這些規則會與它一起載入，而且不會停用直接讀取 `AGENTS.md`。 Cursor 和 Windsurf 也透過各自的 `.cursor/rules/` 和 `.windsurf/rules/` 目錄支援相同作法。AGENTS.md 標準可以參照這些目錄，但跨工具語法尚未完全穩定。比較安全的方式是將共用規則保留在 `AGENTS.md`，並把依路徑適用的規則複製到 `.claude/rules/` 和 `.cursor/rules/`。這些是少數特殊情況，不是大多數規則。 CLAUDE.md 的常用位置，依範圍由大到小排列： | 層級 | 位置 | 用途 | |----|----|----| | **管理政策** | `/Library/Application Support/ClaudeCode/CLAUDE.md`（Mac）、`/etc/claude-code/CLAUDE.md`（Linux） | 企業規則、IT／DevOps | | **使用者** | `~/.claude/CLAUDE.md` | 套用於所有專案的個人偏好 | | **專案** | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 專案團隊規則 | | **本機** | `./CLAUDE.local.md`（加入 `.gitignore`） | 特定專案的個人偏好 | 例如，`~/.claude/CLAUDE.md` 可以只有兩項規則：「使用使用者偏好的語言回覆」和「Ailoot 拼法必須完全一致」。這些規則適用於所有專案，因此不必在每個儲存庫中重複撰寫。 在這四個層級中，只有專案層級的 `CLAUDE.md` 和 `CLAUDE.local.md` 會停用直接讀取 `AGENTS.md`。個人用的 `~/.claude/CLAUDE.md` 和管理政策不會妨礙讀取；Claude Code 會將它們與 `AGENTS.md` 一起讀取。 ## 如果專案中的 AGENTS.md 已經過時，該怎麼辦？
重點摘要 如果 `AGENTS.md` 是 2025 年為 Codex 或 Aider 整理的，而且從那時起就沒編輯過，請在 Claude Code 中開啟專案，要求 Claude 編輯該檔案。AGENTS.md 是持續更新的文件；Linux Foundation 規格也會更新。維持內容更新的主要原則是：每條規則都必須回答「我厭倦了反覆提醒 Claude/Codex 做什麼？」如果沒有，就把它封存。
在本文所述的專案中，我有一份 2025 年 5 月建立的 `AGENTS.md`，共 180 行，其中很多內容已過時（提到了已變更的 Anthropic API endpoint、已不存在的 `claude --tools` 語法範例，以及結構已過時的 `~/.claude/projects/` 規則）。 我採用以下計畫更新它： 1. **在 plan mode 中用 `claude` 檢查。** 我開啟儲存庫，執行 `claude --safe-mode`，然後提出要求：「重新閱讀 `AGENTS.md`，列出已過時或重複的項目。不要編輯，只列出項目。」兩分鐘後，我得到 23 個待檢查項目。 2. **刪除明顯過時的項目。** 23 個項目中，有 9 個明顯已過時，包括指令語法、endpoint 和旗標名稱。我刪除了那些行。 3. **合併重複項目。** 另有 6 個項目用不同說法重複相同內容（「不要強制推送」、「絕不要使用 `--force`」、「避免 `git push -f`」）。我把它們合併成一行。 4. **新增項目。** 我依照「每種錯誤模式一行」的原則，加入過去一個月觀察到 Claude／Codex 經常出錯的地方。結果新增了 8 項。 5. **執行子代理進行最後檢查。** 我要求 Claude 執行審查，指示是「找出矛盾、模糊之處和重複內容」。它找出三處可以改得更清楚的表述，我修正了它們。 一小時後，`AGENTS.md` 變成 110 行，內容已更新，而且我清楚掌握每一行。我也輕易地從中整理出一份 30 行的 `CLAUDE.md`。之後 Codex 執行測試時也明顯更加謹慎——我懷疑它先前某些「奇怪」的決定，是因為它善意地遵守了已過時的指示。 維護 `AGENTS.md` 的主要原則如下： - **每條規則都要對應一種反覆發生的錯誤。** 如果我在一個月內一次都沒想起某條規則，就沒有保留它的必要。 - **把規則寫成指令，而非理論。**「使用兩個空格」是規則；「程式碼風格應該整潔」不是。 - **具體內容勝過籠統說法。**「執行 `git push` 前先執行 `npm run build`」是規則；「測試你的變更」不是。 ## 這種設定有哪些地方肯定行不通？
重點摘要 匯入 `@AGENTS.md` 並不會讓不同工具的行為變得一致。每種工具都有自己的特性：Codex CLI 不知道 `.claude/rules/` 或 hooks。Cursor 有自己的自動補全引擎，補全文字時不會讀取 CLAUDE.md。Copilot 會遵循 `.github/copilot-instructions.md`，只靠 AGENTS.md 中的規則並不足夠。這不是「一個檔案就能統一所有行為」，而是「基準規則只有一個來源，再由各工具加入自己的補充內容」。
在使用這種設定的六個月裡，我吃過一些苦頭，才學到以下幾點： **1. Cursor 自動補全不會使用 AGENTS.md。** Cursor 在編輯器中建議完成某一行時，不會即時讀取 `AGENTS.md`——背後運作的是另一個快速引擎。只有在 Cursor 中透過聊天提出要求時，AGENTS.md 的規則才會生效。這代表在 AGENTS.md 中寫「不要使用 `var`，改用 `const`」不會影響自動補全；你需要透過 ESLint 或 TypeScript 設定來管理。 **2. 寫在 AGENTS.md 中的 Claude Code hooks 對 Codex 無效。** 如果 `.claude/settings.json` 設定了 PreToolUse hook 來封鎖某個動作，這項資訊只有 Claude 用得上。Codex 不知道 hooks；對它而言，就是「工具自己決定」。因此在 `AGENTS.md` 寫「不要做 X」，並在匯入下方的 `CLAUDE.md` 寫「有一個會實際封鎖 X 的 hook」，才是合理作法。 **3. Copilot 和 `.github/copilot-instructions.md`。** GitHub Copilot 會讀取自己的檔案，目前仍無法很好地讀取 AGENTS.md。如果團隊積極使用 Copilot，請另建一份精簡版規則的 `.github/copilot-instructions.md`，或使用支援 AGENTS.md 的 [Copilot Extensions](https://github.com/marketplace?type=apps&category=copilot-extensions)。這方面變化很快，三到六個月後的情況可能就不同了。 **4. Git 不會把符號連結記錄成 CLAUDE.md 的變更。** 如果你執行 `ln -s AGENTS.md CLAUDE.md`，一週後再更新 `AGENTS.md`，Git 只會顯示 `AGENTS.md` 的差異。這是正常現象，但審查 PR 的同事可能不知道 `CLAUDE.md` 也透過符號連結同步更新了。解決方式是在 PR 說明中明確寫上：「已更新 `AGENTS.md`；Claude Code 會透過符號連結看到相同檔案。」 **5. 深層匯入很難偵錯。** 如果 `AGENTS.md` 匯入 `@docs/coding-style.md`，而該檔案又匯入 `@docs/typescript.md`，一旦某條規則與另一條衝突，就很難排查。我會把匯入限制在一層（`CLAUDE.md` → `AGENTS.md`），不再巢狀匯入。Anthropic 提供的 `InstructionsLoaded` hook 會記錄哪些檔案已載入，對偵錯分層設定很有幫助。注意：透過匯入或符號連結納入的 `AGENTS.md` 會觸發這個 hook，但 Claude Code 自行讀取的 `AGENTS.md` 不會。
### 來源 - [Claude Code 記憶說明文件 - AGENTS.md 章節](https://code.claude.com/docs/en/memory#agents-md) - Claude Code 何時會自行讀取 AGENTS.md、「Project instructions」設定、匯入與符號連結，以及 `/init` 的行為。 - [Claude Code 記憶說明文件 - 匯入其他檔案](https://code.claude.com/docs/en/memory#import-additional-files) - `@path/to/file` 語法、最多四層的深度，以及相對路徑和絕對路徑。 - [agents.md - Linux Foundation 標準](https://agents.md/) - AGENTS.md 官方標準及支援工具清單。 - [Cursor Rules 說明文件](https://docs.cursor.com/context/rules-for-ai) - Cursor 會讀取的內容（`.cursor/rules/*.mdc`、AGENTS.md）。 - [GitHub Copilot 自訂指示](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - `.github/copilot-instructions.md` 格式。 - [Linux Foundation 的 AGENTS.md 規格](https://aaif.io/projects/agents-md/) - 持續更新的規格。
一晚就能建立的完整 vibe coding 設定：**AI 分身 + 第二大腦 + 脈絡工程**。 認識 [Ailoot](https://ailoot.ai/)。 ## 常見問題：2026 年 Claude Code、Codex 和 Cursor 的單一指示檔 ### 什麼時候該匯入而非符號連結？ 需要 Claude 特定附加規則，或團隊用 Windows 時，在 CLAUDE.md 用 `@AGENTS.md`。符號連結讓兩名稱指向相同內容，不能另存 Claude 專用區段。 ### 如何確認共用指示已載入？ 用 `/memory` 查看指示檔。設定中若 CLAUDE.md 或 CLAUDE.local.md 抑制直接載入 AGENTS.md，加入匯入或選同時載入的設定，再開新工作階段。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。