AGENTS.md 和 CLAUDE.md 同時存在時，Claude Code 預設只讀 CLAUDE.md：機制、實測與三種解法

你的 repo 裡放了 AGENTS.md，因為團隊有人用 Codex、Cursor 或 Gemini CLI。後來為了 Claude Code 又加了一份 CLAUDE.md。兩個檔案都在，看起來很完整。問題是：Claude Code 很可能從頭到尾沒有讀過那份 AGENTS.md。

這個提醒最近在 r/ChatGPTCoding 被貼出來討論。我們去對了 Claude Code 官方的 memory 文件、GitHub changelog，並在本機的 Claude Code 2.1.322 上用「暗號測試」實際跑了五組情境。結論是：這不是 bug，是文件寫明的預設行為。好消息是它有三種解法，而且其中一種只要在 CLAUDE.md 加一行。

背景：AGENTS.md 是什麼、Claude Code 為什麼拖了一年

AGENTS.md 是一個給 coding agent 讀的專案說明檔，定位就是「給 agent 看的 README」。agents.md 官網說明它由 OpenAI 的 Codex、Amp、Google 的 Jules、Cursor、Factory 等團隊共同推動，目前由 Linux Foundation 旗下的 Agentic AI Foundation 託管，官網宣稱已有超過六萬個開源專案採用。官網列出的相容工具包含 Codex、Jules、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Devin、JetBrains 的 Junie、Amp、Cursor、RooCode、Gemini CLI、Kilo Code、GitHub Copilot coding agent、Windsurf 等。

Claude Code 長期是這張名單上的例外。GitHub 使用者 DylanLIiii 在 2025 年 8 月 21 日開的 issue #6235「Feature Request: Support AGENTS.md」累積了超過 6,600 個表情反應與 400 多則留言。另一位使用者 nathanjohnpayne 在 2026 年 3 月再開 #34235，直接提議「CLAUDE.md 先讀、AGENTS.md 後讀」的順序。直到 2.1.277 版，changelog 才出現這一條：

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config

關鍵字是「in a project with no CLAUDE.md」。它是備援（fallback），不是並讀。這正是 Reddit 那則提醒的核心。

運作原理：Claude Code 啟動時怎麼決定讀哪個檔

把官方 memory 文件的規則攤開，判斷流程是這樣的：

啟動時，Claude Code 從工作目錄一路往上層目錄掃，找 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 三種檔案。
只要在工作目錄或任何一層上層找到其中一個，就只載入 CLAUDE.md 系列。AGENTS.md 完全被跳過。
一個都沒找到，才會載入工作目錄與上層目錄裡的每一份 AGENTS.md 和 .claude/AGENTS.md。

文件的原句是：「By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.」

Claude Code 啟動時決定載入 CLAUDE.md 或 AGENTS.md 的判斷流程

有幾個細節很容易踩到：

哪些檔案「算」擋住 AGENTS.md：專案層的 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md。注意 CLAUDE.local.md 也算。文件特別提醒：你為了個人偏好加一份 CLAUDE.local.md，就會讓 Claude 不再讀 AGENTS.md。
哪些檔案「不算」：你家目錄的 ~/.claude/CLAUDE.md、組織部署的 managed CLAUDE.md、以及 .claude/rules/ 底下的規則檔。有這些存在時，AGENTS.md 仍會一起載入。
永遠不讀的：AGENTS.local.md、AGENTS.override.md，以及任何 .agents/ 目錄底下的東西。其他工具的擴充慣例，Claude Code 不接。
子目錄的 AGENTS.md：和子目錄的 CLAUDE.md 一樣是延遲載入。Claude 用 Read 工具開了那個子目錄的檔案時才會載入，而且條件同樣是該子目錄沒有上述三種 CLAUDE.md。

這個行為是由一個內建外掛控制的，設定名稱叫「Project instructions」，在 /config 裡可以改，共四個值：

設定值	行為
`claude-md-or-agents-md`（預設）	有 `CLAUDE.md` 系列就只讀它；沒有才讀 `AGENTS.md`
`claude-md-and-agents-md`	兩個都讀；每個目錄先 `CLAUDE.md` 再 `AGENTS.md`；已經透過匯入載入過的 `AGENTS.md` 不會重讀
`claude-md`	只讀 `CLAUDE.md`，完全不碰 `AGENTS.md`
`managed-only`	只讀組織 managed `CLAUDE.md` 和 auto memory

寫進 settings 檔的話，鍵值路徑是 pluginConfigs 底下的 cc-plugin-agents-md@builtin，再進 options.instructionFiles。文件註明 2.1.285 之前這個外掛 ID 叫 agents-md@builtin，舊設定檔要留意。

另外三個官方列出的「這些情況讀不到 AGENTS.md」：版本低於 2.1.277；用 /plugin 把內建外掛關掉；從 2.1.276 以前升上來的第一個 session。

實測：五組情境，暗號測法

我們在 Claude Code 2.1.322、claude -p --model haiku 非互動模式下測。做法很簡單：在 AGENTS.md 寫一句「專案暗號是 MANGO-42」，在 CLAUDE.md 寫「次要暗號是 PAPAYA-7」，然後問 Claude 兩個暗號各是什麼，沒被告知的回 NONE。暗號有回來，就代表那個檔案真的進了 context。這個測法和 GitHub 使用者 yurukusa 在 #6235 留言裡用的方法同一個思路，他在 2.1.282 上每組跑三次。

情境	檔案配置	結果
A	只有 `AGENTS.md`	project=MANGO-42。AGENTS.md 有載入
B	`AGENTS.md` + `CLAUDE.md`，無匯入	project=NONE; secondary=PAPAYA-7。AGENTS.md 被跳過
C	`CLAUDE.md` 第一行寫 `@AGENTS.md`	兩個暗號都有
D	同 B，另用 `--settings` 傳入 `claude-md-and-agents-md`	兩個暗號都有
E	`AGENTS.md` + `CLAUDE.local.md`（無 `CLAUDE.md`）	project=NONE。CLAUDE.local.md 一樣擋掉 AGENTS.md

情境 B 就是 Reddit 那則提醒描述的狀況，在最新版上重現。情境 E 驗證了文件說的 CLAUDE.local.md 陷阱。

幾個誠實的限制要說：每組只跑一次、用的是 haiku、非互動模式。另外在情境 D，我們一開始把設定寫在測試目錄的 .claude/settings.json 裡沒有生效，改用 --settings 旗標傳同一份 JSON 才通。我們推測是全新暫存目錄在 -p 模式下的工作區信任問題，沒有再往下追，這點標為不確定。

還有一段歷史要補：2.1.277 剛推出時，Amazon Bedrock、Google Vertex AI、以及關閉遙測的 session 讀不到 AGENTS.md。#6235 裡 S-Luiten 回報設了 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 後 /config 看不到這個選項，logankaser 貼了一篇標題為「只有遙測開著才讀 AGENTS.md」的部落格批評。2.1.281 的 changelog 明確修掉：「Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled」。yurukusa 隨後在 2.1.282 量測，關遙測的那組也是 3/3 通過。如果你看到的二手文章還在講遙測問題，先看它寫的版本號。

三種解法與取捨

AGENTS.md 與 CLAUDE.md 並存的三種解法對比

解法一：CLAUDE.md 第一行寫 `@AGENTS.md`（推薦）

@AGENTS.md

# Claude Code 專屬補充
以下只有 Claude Code 會讀：hooks、skills、權限相關設定。

這是官方文件推薦的做法。@path 匯入是在 harness 層展開的，AGENTS.md 的內容會跟 CLAUDE.md 一起進 context，不靠模型「記得去讀」。好處是：跟 repo 一起 commit，隊友 clone 下來就生效；2.1.277 以前的版本也通；Windows 沒問題。

匯入規則要記住四條：相對路徑是相對於寫匯入的那個檔案，不是工作目錄；最多遞迴四層；寫在 Markdown code span 或 fenced code block 裡的 @ 不會被解析，所以你在 CLAUDE.md 裡用反引號引用 @AGENTS.md 當作說明文字是安全的；路徑有空白要用反斜線跳脫，用引號包起來反而整個不匯入。

解法二：symlink

ln -s AGENTS.md CLAUDE.md

文件說這可行，但列了兩個缺點：Edit 和 Write 工具會拒絕寫穿 symlink，所以你請 Claude「順手把這條規則加進 CLAUDE.md」會失敗；Windows 的 checkout 可能把 symlink 變成一般檔案。官方建議 Windows 團隊用解法一。

順帶一提，#6235 裡 dskvr 分享的做法是在 CLAUDE.md 寫一句純文字「See ./AGENTS.md」再把它 gitignore 掉。這和匯入不同：純文字提示是在模型層，要靠模型自己決定去開檔。同一串裡 ethaizone 就指出，依賴 LLM 記得去抓自己的指令不是穩健做法。能用 @AGENTS.md 就用 @AGENTS.md。

解法三：把設定改成 `claude-md-and-agents-md`

在 /config 找「Project instructions」改值，或寫進 settings。適合你本來就想讓兩份檔各司其職，又不想動 CLAUDE.md 的情況。要注意這是設定，不是 repo 內容：放在使用者層就只有你自己生效；要全隊一致就得放進專案或 managed settings，而我們的實測顯示專案層 settings 在某些情境不一定吃到，上線前要用暗號法驗一次。

另外文件還列了三個透過設定讀 AGENTS.md 時的差異：InstructionsLoaded hook 不會為它觸發；--add-dir 加進來的目錄不會載入它的 AGENTS.md；它裡面若有指向工作目錄外的 @path 匯入，只有在外部匯入已核准過的情況下才會無提示載入。

什麼時候不要「兩個都讀」

如果你的 AGENTS.md 和 CLAUDE.md 內容大量重複，兩個都讀只是浪費 context。更糟的是兩邊規則矛盾。文件對 user rules 與 project rules 衝突的說法是「Claude may follow either one」，兩份專案說明檔衝突時沒有理由期待更好的結果。原則是：共通規則只放一處，Claude 專屬的放另一處。

給工程團隊的落地清單

1. 決定單一事實來源。 跨工具的規則（build 指令、測試方式、程式風格、禁區）放 AGENTS.md。CLAUDE.md 只放 Claude Code 才懂的東西：hooks、skills 位置、權限偏好、.claude/rules/ 的使用說明，然後第一行 @AGENTS.md。

2. 驗證它真的有載入。 三個官方管道：/memory 會列出載入的記憶檔路徑，看 AGENTS.md 有沒有在裡面（2.1.280 以前 /memory 和 /context 不會列直接讀取的 AGENTS.md，舊版要升級再看）；/context all 看 Memory files 區塊；/doctor prompt-audit 會一併審 CLAUDE.md、CLAUDE.local.md、AGENTS.md 和 .claude/ 底下的檔案，不會自動改東西。非互動環境就用上面的暗號法寫成腳本。

3. 在 CI 加一條守門檢查。 有 AGENTS.md 又有 CLAUDE.md，但 CLAUDE.md 沒有匯入它，就讓 pipeline 失敗：

if [ -f AGENTS.md ] && [ -f CLAUDE.md ] && ! grep -qE '^@(\./)?AGENTS\.md\s*$' CLAUDE.md; then
  echo "CLAUDE.md exists but does not import AGENTS.md; Claude Code will skip AGENTS.md" >&2
  exit 1
fi

4. 盯住 CLAUDE.local.md。 它通常被 gitignore，所以隊友不會發現你本機多了一份。只要它在，AGENTS.md 就被擋。解法仍然是在 CLAUDE.md 匯入，因為匯入不受這個判斷影響。

5. 遷移工具。 已經有 AGENTS.md 想長出 CLAUDE.md：/import 會把 AGENTS.md 一次性複製進 CLAUDE.md，但那是複製不是連結，之後兩邊會漂移，我們不建議當長期方案。設了 CLAUDE_CODE_NEW_INIT=1 之後的 /init 會讀 AGENTS.md，也會讀 Cursor 的 .cursor/rules/、.cursorrules 和 Copilot 的 .github/copilot-instructions.md。

6. 看版本號再信文章。 2.1.277 以前完全不讀；2.1.277 到 2.1.280 有遙測與 Bedrock／Vertex 限制；2.1.281 起全平台；2.1.285 改了外掛 ID；2.1.290 修了子目錄 AGENTS.md 在 @ 提及檔案時沒附上的問題。網路上不少文章寫在這些修正之前。

回到 Reddit 那則提醒。它說對了現象，而且這個現象在最新版依然成立。差別在於它不是 Claude Code 壞掉，是 Anthropic 選了「備援」而不是「並讀」當預設。知道這一點之後，CLAUDE.md 第一行加 @AGENTS.md，問題就結束了。

來源

Claude Code 官方文件 Memory 頁（AGENTS.md 載入規則、Project instructions 四個設定值、匯入規則、/memory 與 /doctor prompt-audit）：https://code.claude.com/docs/en/memory
anthropics/claude-code CHANGELOG（2.1.277 新增 AGENTS.md 支援、2.1.281 擴及 Bedrock／Vertex／關遙測、2.1.290 子目錄修正）：https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
GitHub issue #6235「Feature Request: Support AGENTS.md」，DylanLIiii 開啟，含 schizek、S-Luiten、yurukusa、logankaser、dskvr、ethaizone 等人的留言：https://github.com/anthropics/claude-code/issues/6235
GitHub issue #34235，nathanjohnpayne 開啟：https://github.com/anthropics/claude-code/issues/34235
agents.md 官網（格式說明、相容工具清單、Agentic AI Foundation 託管）：https://agents.md/
r/ChatGPTCoding 原始提醒貼文：https://www.reddit.com/r/ChatGPTCoding/comments/1xtlwh6/if_your_repo_has_both_agentsmd_and_claudemd/
本文實測：Claude Code 2.1.322、claude -p --model haiku，2026 年 11 月 12 日

整理：DataAgent · Coding Agent 實戰教學