2026 年 Claude Code、Codex 和 Cursor 的單一指示檔

如需服務相關資訊，請參閱 Ailoot 說明文件。

同時使用 Claude Code、Codex 和 Cursor 時，會有哪些改變？#

在本文的例子中，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 的問題，而是任何有多個事實來源的系統都會遇到的基本陷阱。我在多代理工作指南中更詳細地討論了這個問題。

2026 年 6 月，Anthropic 的 Claude Code 記憶說明文件提出了一個解法：共用檔案加上匯入。自 2026 年 9 月起，如果專案沒有 CLAUDE.md，Claude Code 就會自行讀取 AGENTS.md；如果有 Claude 專用規則，則需要匯入。下文將說明何時只用一個 AGENTS.md 就足夠、如何設定匯入，以及如何區分共用規則和 Claude 專用規則。

Claude Code 會自行讀取 AGENTS.md 嗎？#

在 2026 年 9 月以前，答案是「不會」。要求支援 AGENTS.md 的 Issue #6235 自 2025 年 8 月起一直處於開啟狀態，並於 2026 年 8 月 17 日關閉。在此期間，記憶說明文件一直指出同一個解法：建立 CLAUDE.md，並將 AGENTS.md 作為匯入內容納入其中。從 2.1.277 版開始，說明文件的說法改變了：

Claude Code 讀取的內容，取決於專案中有哪些檔案：

這項檢查會將工作目錄及其上層目錄中的 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.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？#

官方說明文件中的最小可行範例如下：

@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。

以下是說明文件對匯入運作方式的引述：

幾項實用細節：

• 相對路徑和絕對路徑。 @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 中。

什麼時候該選符號連結，什麼時候該選匯入？#

說明文件中展示的符號連結方式如下：

ln -s AGENTS.md CLAUDE.md

接著，文件立刻針對 Windows 提出坦率的警告：

比較表：

本文所述的專案使用匯入，理由如下：

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 設定的偵錯方法，請參閱安全模式指南。

如果沒有 Claude 專用規則，從 2.1.277 版開始就不再需要符號連結：刪除 CLAUDE.md，Claude Code 便會自行讀取 AGENTS.md。只有在團隊中有人使用舊於 2.1.277 的版本，而且無法更新時，才保留符號連結。如果有 Claude 專用規則，十之八九使用匯入會更方便。

Codex、Cursor、Copilot、Windsurf 和 Gemini CLI 會讀取什麼？#

以下是七種主要工具的對照表（根據各工具的官方說明文件）：

這代表什麼？如果儲存庫中有 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？#

Anthropic 在說明文件中這樣描述 /init：

實際上代表什麼？本文所述的儲存庫中有一份我試用 Cursor 時留下的 .cursorrules（約 80 行），以及一份手動整理的 AGENTS.md（120 行）。執行 claude /init 後，指令讀取了兩個檔案，去除相似規則的重複內容，並在一分鐘內整理出一份乾淨的 CLAUDE.md。我之後檢查並稍微編輯了一下——移除過時項目，加入標題結構。這比從頭重寫快得多。

透過環境變數啟用也會讀取 AGENTS.md 的互動模式：

CLAUDE_CODE_NEW_INIT=1 claude

/init 啟動後，Claude 會提出一系列釐清問題：要設定哪些產出項目（CLAUDE.md、技能、hooks）、專案使用什麼技術堆疊，以及測試要用哪些指令。接著，子代理會探索程式碼庫——讀取 package.json、README.md 和設定檔——並補齊缺少的內容。最後會顯示一份提案，你可以在儲存前編輯。如需了解專案啟動時如何設定 Claude Code，請參閱另一份指南。

接下來談談缺點。如果專案已有一份正在使用的 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 專用指示？#

我依照這個原則區分。放進 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 指南。
• 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 又該放什麼？#

如果規則超過 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/ 中的每個檔案都可以加入以下前置資訊：

---
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 的常用位置，依範圍由大到小排列：

例如，~/.claude/CLAUDE.md 可以只有兩項規則：「使用使用者偏好的語言回覆」和「Ailoot 拼法必須完全一致」。這些規則適用於所有專案，因此不必在每個儲存庫中重複撰寫。

在這四個層級中，只有專案層級的 CLAUDE.md 和 CLAUDE.local.md 會停用直接讀取 AGENTS.md。個人用的 ~/.claude/CLAUDE.md 和管理政策不會妨礙讀取；Claude Code 會將它們與 AGENTS.md 一起讀取。

如果專案中的 AGENTS.md 已經過時，該怎麼辦？#

在本文所述的專案中，我有一份 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」是規則；「測試你的變更」不是。

這種設定有哪些地方肯定行不通？#

在使用這種設定的六個月裡，我吃過一些苦頭，才學到以下幾點：

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。這方面變化很快，三到六個月後的情況可能就不同了。

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 不會。

一晚就能建立的完整 vibe coding 設定：AI 分身 + 第二大腦 + 脈絡工程。

認識 Ailoot。