【2026 最新】Claude Code AGENTS.md 教學：CLAUDE.md 該留、該刪，還是雙軌？

2026 年 9 月 18 日，Claude Code 2.1.277 終於加入 Claude Code AGENTS.md 原生讀取。很多團隊第一個反應是：「那現在可以刪掉 CLAUDE.md 了嗎？」先別急。這次更新解決的是相容性，但預設行為是 fallback（備援讀取），不是把兩份檔案自動合併。

這篇專為同時使用 Claude Code、Codex 或其他 Coding Agent 的團隊而寫。我們不靠猜測，會用官方載入規則、三條遷移路徑與四組 canary（像礦坑金絲雀一樣，用一個醒目 token 判斷規則有沒有進入 context）帶你完成驗收。讀完後，你會知道 CLAUDE.md 該留、該刪，還是只留一個薄薄的轉接層。

Claude Code AGENTS.md 先說結論

共享指令架構 ＝ AGENTS.md 共用底稿 ＋ CLAUDE.md 工具薄層 ＋ canary 驗收。把 AGENTS.md 想成建築的公共管線；CLAUDE.md 是 Claude Code 專用的轉接頭。你可以拆掉轉接頭，但前提是所有工作環境都已經能直接接上公共管線。

• 只用 Claude Code，且所有環境都已升到 2.1.277 以上：可以考慮只留 AGENTS.md。
• Claude Code 與 Codex 混用：最穩健的預設是以 AGENTS.md 當唯一共享真相，讓薄 CLAUDE.md 用 @AGENTS.md 匯入，再放 Claude 專屬規則。
• 仍有舊版、Bedrock、Vertex 或 Foundry session：先保留薄 CLAUDE.md；截至 2026 年 9 月 19 日，2.1.277 發行說明仍明列這些環境尚未提供直接讀取。
• 最不建議：在兩份檔案複製同一套完整規則。短期看似相容，長期一定多一個漂移面。

Claude Code AGENTS.md 怎麼讀？Fallback 不等於 Merge

Anthropic 的現行 memory 官方文件把預設值寫得很清楚：當目前工作目錄與其上層存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 時，Claude Code 讀 Claude 指令檔；只有這三種檔案都不存在時，才直接讀 AGENTS.md。所以「支援 AGENTS.md」不等於「兩份都會生效」。

這裡最容易踩到的是 CLAUDE.local.md。它通常被放進 .gitignore，同事看不到，卻仍會讓你自己的 session 停止走預設 AGENTS.md fallback。若你的電腦結果和 CI、同事不同，第一件事不是懷疑模型，而是沿著目前目錄一路往上找這三種檔案。

巢狀目錄也不是一次把全 repo 掃光。Claude Code 啟動時會讀目前目錄與上層的指令；當它用 Read 打開子目錄檔案時，才按該子目錄的條件載入更深的指令。這和 Codex 從專案根目錄一路走到目前工作目錄、每層選一份檔案的做法相似，但檔名優先序與載入時機並不完全相同。想先理解規則分層與強制閘門，可搭配AGENTS.md 五道閘門教學。

三條遷移路徑：刪除、薄轉接，還是完整雙軌？

選擇的重點不是「哪個檔名比較新」，而是你要維護幾份真相，以及最舊的執行環境在哪裡。

路徑 A：只留 AGENTS.md

適合所有 Claude Code session 都在 2.1.277 以上、能取得這項功能，而且沒有 Claude 專屬設定的 repo。優點是最乾淨；代價是舊版與目前未支援的第三方 provider session 只會讀 CLAUDE.md，你必須接受它們暫時拿不到專案指令，或另行提供相容層。

路徑 B：AGENTS.md ＋薄 CLAUDE.md（推薦）

把跨工具共用規則全部放進 AGENTS.md，再讓 CLAUDE.md 只做匯入與 Claude 專屬 overlay（疊加層）。Anthropic 官方也直接建議這種共享方式：

@AGENTS.md

## Claude Code only

- 修改 src/billing/ 前先進入 plan mode。
- 用 /context 確認本次 session 的專案指令。

@AGENTS.md 是真正的檔案匯入，不是「請記得去讀」的自然語言提醒。官方也說明，已匯入或 symlink 到同一份 AGENTS.md 時，切到同時載入模式不會再重複塞第二份。這條路保留相容性，又把共享內容鎖在單一來源。若你的規則已經膨脹，先用CLAUDE.md 指令整理法刪掉過期內容，再搬家。

路徑 C：兩份完整規則各自維護

只有在兩個工具的規則本來就高度不同、而且你願意為每次修改做雙向 review 時才合理。不要把同一段 build、test、安全規則複製兩次；衝突指令不是可靠的優先序設計，Claude 官方文件甚至提醒，兩條規則矛盾時模型可能任選其一。真正該硬性阻擋的行為，應放進 Hook、CI 或權限層；可參考Agent CAPA 實作教學。

用 4 個 fixture 驗收 Claude Code AGENTS.md

不要在正式 repo 直接刪檔。先建立四個最小 fixture（測試用小型專案），每份指令放一個互斥 token。以下流程是依官方規則設計的可重現驗收，不是 AlphaLab 在 2.1.277 本機 session 的實測結果。

mkdir -p /tmp/cc-instructions/{only-agents,only-claude,both,nested/apps/web}

printf '# Rule\nReply with CANARY_AGENTS only.\n' \
  > /tmp/cc-instructions/only-agents/AGENTS.md

printf '# Rule\nReply with CANARY_CLAUDE only.\n' \
  > /tmp/cc-instructions/only-claude/CLAUDE.md

printf '# Rule\nReply with CANARY_AGENTS_BOTH only.\n' \
  > /tmp/cc-instructions/both/AGENTS.md
printf '# Rule\nReply with CANARY_CLAUDE_BOTH only.\n' \
  > /tmp/cc-instructions/both/CLAUDE.md

printf '# Rule\nRemember CANARY_ROOT.\n' \
  > /tmp/cc-instructions/nested/AGENTS.md
printf '# Rule\nRemember CANARY_WEB.\n' \
  > /tmp/cc-instructions/nested/apps/web/AGENTS.md

1. 固定版本：先跑 claude --version，確認是 2.1.277 以上。若剛升級，關掉第一個 session，再開一個新 session；官方文件說直接讀取可能要從升級後的下一個 session 才生效。
2. 確認模式：在 Claude Code 輸入 /config，檢查 Project instructions。預設值應是 claude-md-or-agents-md。
3. 逐一啟動：分別進入四個目錄開新 session，要求「只回覆目前專案指令要求的 canary token」。互斥 token 能讓你看見真實來源，不必用主觀回答猜測。
4. 檢查巢狀載入：從 nested 啟動後，先問 root token，再要求 Claude 用 Read 打開 apps/web 內一個檔案，確認子目錄指令是否在需要時加入。
5. 保存結果：把版本、Project instructions 值、啟動目錄、看到的 token 與 session 時間記進 PR。這才是可回歸的遷移證據。

在預設模式，預期關係是：only-AGENTS 看見 AGENTS token；only-CLAUDE 看見 CLAUDE token；both 只走 CLAUDE；nested 在讀到子目錄檔案後才加入更深指令。若結果不同，先檢查祖先目錄與隱藏的 CLAUDE.local.md，再檢查版本與 provider，不要立刻改正式規則。

再跑一輪 Claude Code／Codex 跨工具回歸

Claude Code 通過，不代表 Codex 的巢狀規則完全相同。OpenAI 的官方 AGENTS.md 文件說明，Codex 預設從專案根目錄走到目前目錄，每層依序尋找 AGENTS.override.md、AGENTS.md，再找使用者設定的 fallback 檔名；較接近目前目錄的內容排在後面。它不會因為 repo 裡有 CLAUDE.md 就自動改讀那份檔案。

cd /tmp/cc-instructions/only-agents
codex --ask-for-approval never "只回覆目前指令中的 canary token"

cd /tmp/cc-instructions/nested/apps/web
codex --ask-for-approval never "依載入順序列出 canary token"

你的 PR 驗收至少要有四格：Claude Code root、Claude Code nested、Codex root、Codex nested。每格記「預期來源、實際 token、pass/fail」。若團隊還用 Cursor、Gemini CLI 或其他 Agent，再加欄位，不要因為它們都認得 AGENTS.md 就假設優先序相同。更完整的跨 Agent session 驗收，可以接著看Skillsync 8 項驗收法；工具選擇本身則可參考Claude Code vs Codex 客觀比較。

什麼時候才需要「兩份都載入」？

Claude Code 的 /config 可以把 Project instructions 改成 claude-md-and-agents-md。此時每個目錄先放入 Claude 指令，再放 AGENTS 指令；已匯入或 symlink 的同一份檔案會去重。這適合除錯或個人需要，但不該成為 repo 唯一的相容性保證。

原因是這個選項屬於使用者、CLI --settings 或 managed settings；官方文件明確說 project 與 local settings 裡的同名設定會被忽略。換句話說，你不能只提交一份 .claude/settings.json，就保證所有 clone 都切到「both」。若 repo 的正確性依賴兩份內容，請用薄 CLAUDE.md 的 @AGENTS.md 明確建立關係。

舊版本與第三方 Provider 怎麼 rollback？

截至 2026 年 9 月 19 日，Claude Code 2.1.277 官方發行說明仍註明這項直接讀取尚未提供給 Bedrock、Vertex 與 Foundry；memory 文件也列出停用 telemetry、停用相關 built-in plugin 或 managed hook 限制等情況。遇到這些 session，保守策略不是複製兩份內容，而是讓 CLAUDE.md 保留 @AGENTS.md。

1. 遷移前打 tag：保留最後一個雙檔可用版本與 canary 結果。
2. 先上薄轉接：讓新舊 Claude Code 與 Codex 都有路可走，再觀察一個完整開發週期。
3. 出現漏載就復原：還原薄 CLAUDE.md 即可，不必把共享規則從 Git 歷史手抄回來。
4. 最後才刪：只有當支援矩陣每一格都通過，而且沒有 Claude 專屬 overlay，才刪除轉接檔。

這也是為什麼「直接刪掉 CLAUDE.md」不是版本更新後的第一步。先把共享規則收斂成單一來源，再用可觀察 token 驗證每個執行面，風險會小很多。若你還在判斷 AGENTS.md、Skill、Hook 與 MCP 的先後順序，可先讀AI Coding Agent 最小配置。

Claude Code AGENTS.md 常見 6 個坑

1. 把 fallback 說成 merge：預設兩檔並存時只走 Claude 指令，不會自動合併。
2. 漏看祖先目錄：上層任一 CLAUDE.md 都可能改變目前 repo 的結果。
3. 漏看 CLAUDE.local.md：它不一定進 Git，卻會阻止預設 AGENTS fallback。
4. 只在舊 session 測：新版本、設定值與指令鏈都應用全新 session 驗收。
5. 用自然語言叫 Claude 自己讀：一句「請讀 AGENTS.md」不等於匯入；使用真正的 @AGENTS.md。
6. 把文件當強制控制：兩種 Markdown 都是模型 context。測試、資安或合併條件仍要放進 deterministic gate；理解完整執行層可讀AI Agent Harness 是什麼。

FAQ：CLAUDE.md 該留還是刪？

1. 有 AGENTS.md 後，可以立刻刪 CLAUDE.md 嗎？

不建議立刻刪。先確認每個 Claude Code session 都是 2.1.277 以上、功能可用、canary 通過，也沒有 Claude 專屬 overlay；否則先留薄轉接檔。

2. 兩份檔案並存時，預設會讀哪一份？

讀 CLAUDE.md 系列。只要目前目錄或上層有符合條件的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，預設就不直接走 AGENTS.md。

3. 怎麼讓 Claude Code 兩份都讀？

用 /config 選 claude-md-and-agents-md。但這是使用者／managed 層的選項；repo 要可攜，仍以 @AGENTS.md 薄轉接較清楚。

4. @AGENTS.md 會不會重複載入？

官方設計會去重。當 AGENTS.md 已經透過 import 或 symlink 載入，同時載入模式不會再塞一份相同檔案。

5. Codex 會讀 CLAUDE.md 嗎？

預設不會。Codex 的標準發現鏈是 AGENTS.override.md、AGENTS.md 與使用者自訂的 fallback 檔名；若刻意把 CLAUDE.md 加進 fallback 才會納入，但共享規則仍建議放標準 AGENTS.md。

6. AGENTS.override.md 對 Claude Code 有效嗎？

直接讀取模式不會讀。Anthropic 官方目前列出的排除項目包含 AGENTS.override.md、AGENTS.local.md 與 .agents/；這點和 Codex 不同。

7. /context 沒看到 AGENTS.md，就代表沒載入嗎？

不一定。官方文件說直接透過 Project instructions 讀取的 AGENTS.md 不列在 Memory files；預設模式可看啟動時的 AGENTS.md loaded 訊息，再用 canary 問答驗證。

8. AGENTS.md 可以取代測試與 Hook 嗎？

不能。它和 CLAUDE.md 都是提供給模型的 context，不是強制設定。能客觀判定的品質、安全與部署條件，仍應交給 lint、test、Hook、CI 與權限政策。

給新手的 5 個遷移重點

1. 先把共享規則集中到一份 AGENTS.md，不要先刪檔。
2. 讓 CLAUDE.md 只保留 @AGENTS.md 與 Claude 專屬 overlay。
3. 用 only-AGENTS、only-CLAUDE、both、nested 四組 fixture 開新 session。
4. 對 Claude Code 與 Codex 各跑 root／nested 驗收，把 token 結果留在 PR。
5. 所有執行環境都通過後，才決定是否移除薄轉接；需要硬性保證的規則另做 gate。