Claude Code 讀 AGENTS.md 的隱藏規則：多一個 CLAUDE.local.md，團隊規範就悄悄失效

瀏覽次數: 1

你在團隊 repo 裡老老實實維護一份 AGENTS.md，Codex、Cursor、Copilot 都吃得到。Claude Code 從 v2.1.277 開始也會直接讀它，不用再額外放 CLAUDE.md。聽起來終於統一了。

然後某天你在專案根目錄丟了一個 CLAUDE.local.md，只寫兩行自己的沙盒網址，也加進 .gitignore。從那一刻起，Claude Code 在你這台機器上就不再讀 AGENTS.md。沒有錯誤訊息，沒有警告，團隊規範就這樣從 context 裡消失。你只會覺得「Claude 今天怎麼不照規矩跑測試」。

這個坑最早在 r/ChatGPTCoding 的討論串被拿出來講，標題就是「Claude Code reads AGENTS.md now, but one personal file」。好消息是：這不是 bug，是官方文件寫明的行為，Anthropic 在 Claude Code 的 Memory 文件裡甚至用一個 Note 特別提醒。壞消息是：多數人不會去讀那個 Note。

這篇把規則拆清楚，再給你四種修法、一支檢查腳本，讓你五分鐘內確認自己有沒有中招。

本文大綱

一、先搞懂：Claude Code 什麼時候讀 AGENTS.md

根據 Claude Code 官方文件〈How Claude remembers your project〉的 AGENTS.md 章節，預設行為是一條非常單純的規則：

只有在你的工作目錄以及所有上層目錄都沒有 CLAUDE.md 時，Claude 才會讀 AGENTS.md。

官方給的對照表整理如下：

repo 裡有什麼	Claude 讀什麼
只有 `AGENTS.md`，工作目錄與上層都沒有 `CLAUDE.md` 或 `CLAUDE.local.md`	`AGENTS.md`
`AGENTS.md` 加上任何一個 `CLAUDE.md` 或 `CLAUDE.local.md`	只讀 CLAUDE.md 那一家
`CLAUDE.md` 裡寫了 `@AGENTS.md` import	`CLAUDE.md`，`AGENTS.md` 透過 import 一起進來

關鍵在於「哪些檔案算數」。文件把它切成兩組：

算數（出現就讓 AGENTS.md 被略過）：工作目錄或任一上層目錄裡的 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md
不算數（和 AGENTS.md 和平共存）：你的 ~/.claude/CLAUDE.md、組織的 managed CLAUDE.md、.claude/rules/ 底下的檔案

所以問題來源很清楚：CLAUDE.local.md 雖然是「個人、不進版控」的檔案，在這條規則裡它跟團隊的 CLAUDE.md 是同一家人。官方文件原文是這麼說的：因為 CLAUDE.local.md 算數，在一個依賴 AGENTS.md 的專案裡加一個它來放自己的指令，會讓 Claude 對你停止讀取 AGENTS.md。

二、為什麼這個坑特別難發現

1. 只壞在你的機器上。 CLAUDE.local.md 被 gitignore，同事 clone 下來一切正常。你回報「Claude 不照 AGENTS.md 做」，別人重現不出來。

2. 沒有錯誤，只有一行「消失的提示」。 文件提到，當 Claude 真的讀了 AGENTS.md，互動模式下會在對話裡出現一行類似 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 的訊息。中招時這行不會出現，但沒人會注意「少了一行」。

3. 上層目錄也算。 規則寫的是「工作目錄或任一上層目錄」。依字面推論，如果你習慣把所有專案放在 ~/work/，又在 ~/work/CLAUDE.md 放了自己的通用筆記，底下每個只靠 AGENTS.md 的 repo 都會一起被略過。注意這跟 ~/.claude/CLAUDE.md 不同，後者明確列在「不算數」那組。這點是從文件規則推出來的，值得你在自己的目錄結構上實測一次。

4. worktree 讓行為不一致。 文件提醒過，gitignore 的 CLAUDE.local.md 只存在於你建立它的那個 worktree。結果是：主目錄的 Claude 不讀 AGENTS.md，另一個 worktree 裡的 Claude 卻有讀。同一個 repo，兩種人格。

5. 有些 AGENTS 家族檔案根本不讀。 文件明列 Claude Code 不讀 AGENTS.local.md、AGENTS.override.md，以及 .agents/ 目錄底下的任何東西。如果你從 Codex 那邊帶過來習慣用 AGENTS.override.md 放個人覆寫，在 Claude Code 這邊它是不存在的。

三、五分鐘自我檢查

步驟 1：看 /context。 在專案裡開一個 Claude Code session，輸入 /context，看 Memory files 清單。官方 troubleshooting 的原話是：清單裡沒出現的檔案，Claude 就看不到。你要確認 AGENTS.md 在裡面。

步驟 2：用腳本往上掃「算數」的檔案。 在 repo 裡跑這段（POSIX shell 可用）：

d="$PWD"
while :; do
  for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do
    [ -e "$d/$f" ] && echo "會讓 AGENTS.md 被略過：$d/$f"
  done
  [ "$d" = "/" ] && break
  d=$(dirname "$d")
done

有任何輸出，而你的團隊規範只寫在 AGENTS.md，你就中招了。

步驟 3：看啟動訊息。 開新 session 時注意有沒有 AGENTS.md loaded 那一行。沒有就回到步驟 2。

步驟 4（選用）：讓 Claude 幫你稽核。 v2.1.283 以後可以跑 /doctor prompt-audit。依文件，它預設會檢查 CLAUDE.md、CLAUDE.local.md、AGENTS.md 以及 .claude/ 底下的 rules、skills 等，找出互相矛盾或引用不存在檔案的指令，並在你同意前不改任何檔案。

四、四種修法，照情境選

修法 A：把 Project instructions 改成「兩個都讀」（個人最快）

在 session 裡輸入 /config，找到 Project instructions，改成 claude-md-and-agents-md。四個可選值依文件是：

claude-md-or-agents-md：預設，有 CLAUDE 家族就不讀 AGENTS.md
claude-md-and-agents-md：兩者都讀，每層目錄先 CLAUDE.md 再 AGENTS.md；已經透過 import 或 symlink 讀過的 AGENTS.md 不會重複載入
claude-md：只讀 CLAUDE 家族
managed-only：啟動時只讀組織 managed 指令與 auto memory

想寫進設定檔讓每台機器一致，放在 ~/.claude/settings.json：

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

兩個細節別踩：第一，這個設定只在 ~/.claude/settings.json、--settings 指定的檔案或 managed settings 生效，寫在專案的 .claude/settings.json 或 settings.local.json 會被忽略，所以你沒辦法用 commit 一份專案設定替全隊開。第二，v2.1.285 以前這個內建 plugin 的 ID 是 agents-md@builtin，舊版本不認新 ID；v2.1.285 之後兩個都認。團隊版本不齊的話，用舊 ID 最保險。

修法 B：在 CLAUDE.local.md 第一行 import AGENTS.md（不碰設定）

@AGENTS.md

## 我的個人設定
- 測試資料庫用 localhost:5433
- 我的沙盒網址 https://dev-abao.example.com

CLAUDE.local.md 依文件「載入方式與 CLAUDE.md 相同」，@path import 會在啟動時展開，相對路徑以檔案本身所在位置為準。這招的好處是不依賴 Claude Code 版本，連 AGENTS.md 支援不可用的 session（例如舊版、或你用 /plugin 關掉了內建 plugin）也有效。缺點是每個 worktree 都要各放一份。

修法 C：個人筆記搬去「不算數」的位置

既然 ~/.claude/CLAUDE.md 和 .claude/rules/ 不會觸發略過，你可以：

全域偏好（例如「回覆用繁中」「commit 訊息用 conventional commits」）放 ~/.claude/CLAUDE.md
只屬於這個專案的個人筆記放 .claude/rules/personal.md，並把這個路徑加進 .gitignore

第二種要注意：.claude/rules/ 本來是給團隊共享規則的地方，你得確保自己的檔案真的被 ignore，別不小心 commit 進去。

修法 D：團隊 commit 一份 `CLAUDE.md`，內容只有 `@AGENTS.md`（最穩）

@AGENTS.md

## Claude Code
- 改動 src/billing/ 底下的檔案前先進 plan mode

這是官方文件「Share one file with other coding tools」章節推薦的寫法。repo 裡一旦有這份 CLAUDE.md，任何人再加 CLAUDE.local.md 都只是「多一份」，AGENTS.md 依然透過 import 進來，不論預設值怎麼設、不論有沒有 Bedrock 或舊版本。文件也明說：保留這個 import 不會讓 AGENTS.md 被讀兩次。

如果不需要 Claude 專屬內容，ln -s AGENTS.md CLAUDE.md 也行，但文件列了兩個限制：Edit/Write 工具拒絕透過 symlink 寫入，會改去編輯 AGENTS.md 本體；Windows 上 symlink 需要管理員權限或開發者模式，且 Git 在沒開 core.symlinks 時會把它 checkout 成一行純文字，那位同事的 CLAUDE.md 就只剩一行路徑。有 Windows 隊友，就用 import。

五、直接讀 AGENTS.md 和 CLAUDE.md 不完全一樣

就算你確定 AGENTS.md 有被讀到，文件也列了三個與 CLAUDE.md 的差異，做自動化的人要留意：

	`CLAUDE.md`	透過設定直接讀的 `AGENTS.md`
`InstructionsLoaded` hook	會觸發	不觸發（被 CLAUDE.md import 或 symlink 的才會）
`--add-dir` 加進來的目錄（有開 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`）	會載入	不載入
`@path` import 工作目錄外的檔案	跳出核准對話框	只有先前核准過才載入，且不再詢問

實務意義：如果你用 InstructionsLoaded hook 做稽核（例如記錄哪些指令檔被載入），只靠 AGENTS.md 的 repo 在 log 裡會是空的。這又是一個支持修法 D 的理由。

另外文件也提醒，子目錄的 AGENTS.md 只有在 Claude 用 Read 工具開了那個子目錄裡的檔案、而且該子目錄自己沒有任何 CLAUDE 家族檔案時才會載入。monorepo 裡各 package 自帶 AGENTS.md 的團隊，同樣適用「一個 CLAUDE.md 就讓它整層失效」的規則。

六、清掉舊的 workaround

在 Claude Code 原生支援之前，很多人自己土炮過讓它讀 AGENTS.md。文件對每種舊做法都給了處置建議：

CLAUDE.md 裡寫 @AGENTS.md：留著沒關係，不會重複讀。
CLAUDE.md 用文字叫 Claude「請先讀 AGENTS.md」：這是最弱的一種，Claude 只有在「決定去開檔」時才看得到。刪掉它，或改成 @AGENTS.md import。更糟的是，這份 CLAUDE.md 本身就會讓原生讀取被略過。
CLAUDE.md symlink 到 AGENTS.md：不用動。
SessionStart hook 印出 AGENTS.md：刪掉。原生讀取上線後，它只會在 context 裡塞第二份重複內容，白燒 token。

七、給團隊的落地清單

repo 層：commit 一份只含 @AGENTS.md（加上少量 Claude 專屬規則）的 CLAUDE.md。這一步就讓個人檔案不再能「關掉」團隊規範。
README 或 onboarding 文件：寫一句「個人設定請放 CLAUDE.local.md，第一行保留 @AGENTS.md」，或指向 ~/.claude/CLAUDE.md。
版本：確認大家至少在 v2.1.281 以上。依 changelog，v2.1.277 加入 AGENTS.md 支援，v2.1.281 才擴大到 Amazon Bedrock、Google Vertex AI、Microsoft Foundry、LLM gateway 與關閉 telemetry 的 session。
CI 或 pre-commit 檢查（選用）：如果團隊堅持不放 CLAUDE.md，至少在文件裡寫清楚上面那支掃描腳本，讓遇到怪行為的人第一時間自查。
別把 CLAUDE.md 當執行保證：文件反覆強調，這些檔案是 context，以 user message 形式送進去，不是強制設定。真的要擋「不准 push main」這類動作，用 PreToolUse hook 或 permissions.deny。

這件事的取捨

Anthropic 選擇「有 CLAUDE.md 就不讀 AGENTS.md」作為預設，其實有道理：很多 repo 兩份都有，內容可能早就分歧，預設兩份都讀容易出現互相矛盾的指令，而文件自己也說，指令衝突時 Claude 可能任選其一。問題只出在 CLAUDE.local.md 這個「個人」檔案被劃進同一組，直覺上它應該是疊加，而不是取代。

你的判斷準則很簡單：團隊規範的唯一真實來源是 AGENTS.md，就讓 repo 裡有一份 import 它的 CLAUDE.md。 個人層級的調整，要嘛 import、要嘛搬到不算數的位置。做完這兩件事，這個坑就跟你沒關係了。

來源

Anthropic，Claude Code 官方文件〈How Claude remembers your project〉，AGENTS.md、Import、Troubleshoot 章節：https://code.claude.com/docs/en/memory
Anthropic，Claude Code CHANGELOG（v2.1.277 加入 AGENTS.md 支援、v2.1.281 擴大支援範圍）：https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
r/ChatGPTCoding 討論串〈Claude Code reads AGENTS.md now, but one personal file…〉：https://www.reddit.com/r/ChatGPTCoding/comments/1x0odt7/claude_code_reads_agentsmd_now_but_one_personal/
AGENTS.md 開放格式說明：https://agents.md