Claude Code 開始讀 AGENTS.md 了，你那個只有一行的 CLAUDE.md 還要留嗎

你的 repo 根目錄放著一份 AGENTS.md，旁邊躺著一個只有一行字的 CLAUDE.md，內容是 @AGENTS.md。這個檔案當初是為了讓 Claude Code 讀得到規範才加的。9 月 18 日之後，它還有存在的理由嗎？

這篇是 8 月 8 日那篇《同一個 repo 兩個 agent：Codex 讀 AGENTS.md，Claude Code 不讀》的更新版。那篇的核心事實是 Claude Code 完全不讀 AGENTS.md，這件事在 41 天後被 Claude Code 自己推翻了。舊文寫的是當時的事實，後來產品換了行為，官方文件也跟著改寫，甚至多開了一節專門教你拆掉以前搭的東西。

八月的時候，你得自己帶轉接頭

出國旅行，插頭形狀不對，你會在行李箱塞一個轉接頭。八月的 Claude Code 就是那個插頭形狀不對的電器：AGENTS.md 是 Linux Foundation 底下的開放標準檔名，Codex 等工具都讀，Claude Code 只認 CLAUDE.md（含 .claude/CLAUDE.md 與 CLAUDE.local.md）。規範寫在 AGENTS.md，它就視而不見，而且不報錯。

舊文當時給的建議是「規範本體寫在 AGENTS.md，CLAUDE.md 當轉接頭」，轉接頭長這樣：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

或者一行 symlink：

1	ln -s AGENTS.md CLAUDE.md

現在回頭看，官方文件把那段時間大家自製的轉接頭整理成四種：用 @AGENTS.md import 的 CLAUDE.md、symlink 到 AGENTS.md 的 CLAUDE.md、用 SessionStart hook 在開場把 AGENTS.md 印出來，還有第四種，在 CLAUDE.md 裡用文字寫一句「請去讀 AGENTS.md」。

第四種最不牢靠。官方原文對它只有一句：

Claude sees AGENTS.md only if it decides to open the file.

那句話只是一個請求。Claude 可能照做，也可能覺得這次不需要，你分不出來它這一場到底讀了沒有。前三種至少會把內容真的塞進 context，這一種是在賭。

9 月 18 日之後：牆上直接有萬用插座

v2.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

背後是一個內建的 plugin，名字就叫 agents-md。官方 memory 文件把它的目的寫得很直接：已經替其他 coding agent 設定好的 repo，不必再加 CLAUDE.md、不必 import、不必動設定，就能用。

規則照官方那張預設判斷表，只有三種情況。專案有 AGENTS.md，而工作目錄與上層目錄都沒有 CLAUDE.md 或 CLAUDE.local.md，它讀 AGENTS.md。兩種都有，它只讀 CLAUDE.md。CLAUDE.md 本來就 import 了 AGENTS.md，就照 import 讀進來。

旅館牆上裝了萬用插座，你不用再掏轉接頭。它讀的範圍也不只根目錄那一份：session 開始時，工作目錄與上層每一層的 AGENTS.md 和 .claude/AGENTS.md 都會進來；Claude 用 Read 工具開某個子目錄的檔案，而那個子目錄沒有自己的 CLAUDE.md 系列檔案時，那裡的 AGENTS.md 會跟著載入。AGENTS.md 裡寫的 @path import 一樣會展開。

互動式 session 裡有一個看得見的訊號，官方文件舉的例子是這行：

1	no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

要注意幾個它刻意不讀的檔名：AGENTS.local.md、AGENTS.override.md，以及任何 .agents/ 目錄底下的東西。舊文花了一整節講 Codex 的 AGENTS.override.md 會整份取代同目錄的 AGENTS.md，這個語意 Claude Code 沒有跟進，它直接不看。

四個轉接頭，各自的下場

官方那節「Remove an earlier AGENTS.md workaround」給了逐項處理方式，我照自己在意的程度重新排過。

SessionStart hook 印出 AGENTS.md 的做法，要拆，而且越早越好。原因是 Claude 現在自己會讀，hook 再印一次，context 裡就有兩份一樣的規範。兩份都是你寫的，內容不會打架，但你在白白燒 context，規範越長燒越多。

文字提醒的那種 CLAUDE.md，也要處理，官方的建議是刪掉讓 Claude 直接讀 AGENTS.md，或把那句話換成 @AGENTS.md。留著那個檔案不只是多餘。照前面那張判斷表，只要它存在，它就算一份 CLAUDE.md，預設規則會因此改成「只讀 CLAUDE.md」，萬用插座直接不通電，你又回到賭 Claude 會不會自己去開檔的狀態。

symlink 可留可刪，官方說兩種情況 Claude 都只讀一次內容。

最後是開頭那個只有一行 @AGENTS.md 的 CLAUDE.md。官方說可以留，import 在任何設定值下都不會讓 AGENTS.md 被讀兩次；檔案裡沒有別的內容就可以刪，但如果有些 session 讀不到 AGENTS.md，就留著。

我的立場是先留著。那一行的成本幾乎是零，拆掉之後萬一團隊裡有人落在讀不到的那幾種 session（後面會列），他那邊就會回到八月的狀態，而且一樣不會報錯。等我能確認團隊每個人都在 v2.1.281 以上、沒人停用內建的 agents-md plugin，我才會拆。在那之前，這個轉接頭插著不礙事。

讓我意外的是 CLAUDE.local.md

整份文件裡最值得停下來看的是這條：哪些檔案「算數」，會讓 Claude 改讀 CLAUDE.md、不讀 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 後面」，是你個人不 commit 的補充筆記。直覺上它是配角，放個 sandbox 網址、自己偏好的測試資料。可是在新規則裡，這個配角一出現，主角 AGENTS.md 就下台了。

換回插座的比喻：這個萬用插座有個怪脾氣，只要延長線上已經插著別的插頭，它就自動斷電。團隊的 repo 靠 AGENTS.md 運作，全隊都好好的，只有你為了放幾行私人設定建了一個 CLAUDE.local.md，然後你的 Claude 從此看不到團隊規範。別人的沒事，你的有事，你會花很久才懷疑到那個檔案頭上。

官方文件自己也用一個 Note 提醒這件事：在依賴 AGENTS.md 的專案裡加一個 CLAUDE.local.md，Claude 就不再替你讀 AGENTS.md。想兩個都要，要把 Project instructions 設成 claude-md-and-agents-md。

/config 的 Project instructions 有四個值。預設的 claude-md-or-agents-md 就是前面那個互斥邏輯；claude-md-and-agents-md 兩種一起讀，每個目錄先讀 CLAUDE.md 再讀 AGENTS.md，已經被 import 或 symlink 讀過的 AGENTS.md 會跳過不重讀；claude-md 只讀 CLAUDE.md，等於回到八月；managed-only 只留組織的 managed CLAUDE.md 與 auto memory，專案、local、使用者層的 CLAUDE.md、.claude/rules/ 與所有 AGENTS.md 都排除。

不想開面板，也可以寫進設定檔，掛在內建 plugin 的 ID 底下：

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

位置有講究。這段只在 ~/.claude/settings.json、--settings 指定的檔案、或 managed settings 裡有效，寫在專案層與 local 層的設定檔會被忽略。你沒辦法把它 commit 進 repo 的 .claude/settings.json 讓全隊一起生效，要嘛每個人在自己的使用者設定裡改，要嘛走組織的 managed settings。

萬用插座沒通電的那幾間房

新做法不是在每個環境都成立。官方列了幾種讀不到 AGENTS.md 的 session，這時 /config 面板連 Project instructions 這個選項都不會出現：Claude Code 版本在 v2.1.277 之前；你在 /plugin 裡停用了內建的 agents-md；從 v2.1.276 以前升級上來之後的第一個 session，下一個 session 才生效。另外，v2.1.281 之前，有些環境只讀 CLAUDE.md，官方舉的例子是 Amazon Bedrock 與關閉 telemetry 的環境。這些情況的退路，正是八月那個 @AGENTS.md import。

就算讀到了，直接讀進來的 AGENTS.md 跟 CLAUDE.md 也有三處行為不同。InstructionsLoaded hook 對 CLAUDE.md 會觸發，對直接讀取的 AGENTS.md 不觸發；如果那份 AGENTS.md 是透過 CLAUDE.md import 或 symlink 進來的，就照常觸發。用 --add-dir 加進來的目錄，在設了 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 的情況下，那裡的 CLAUDE.md 會載入，AGENTS.md 不會。AGENTS.md 裡指向專案外的 @path import，只有在這個專案已經核准過外部 import 時才會載入，而且不會再跳核准提示。

第一條最容易出事。如果你有一段自動化靠 InstructionsLoaded 記錄這場 session 載入了哪些指示檔，把 symlink 或 import 拆掉、改讓 Claude 直接讀 AGENTS.md 之後，那段紀錄就少了一筆，而且不會有任何錯誤告訴你。這又是一個「留著轉接頭反而比較安全」的理由。

這篇的內容全部來自 Claude Code 官方的 memory 文件與 changelog。我只讀了文件，沒有實際跑過：沒有開 /config 看過 Project instructions，沒有建測試專案驗證 CLAUDE.local.md 會擋掉 AGENTS.md，也沒有觸發過 InstructionsLoaded hook。上面描述的行為都是官方文件寫的，不是我實測的結果。

轉接頭拆不拆，其實是另一個問題

八月的時候，你的工作是「想辦法讓 Claude 讀到 AGENTS.md」，四種轉接頭都在解這件事。插座裝好之後，工作反過來了，變成「別讓任何東西擋住它讀」。照官方的判斷規則，會擋住它的是一個多出來的 CLAUDE.local.md，或一個只剩一句文字提醒的舊 CLAUDE.md。至於那個你以為 commit 進 repo 就能讓全隊改成兩種都讀的專案層設定，它不會擋，只是會被忽略，救不了你。

開一個新 session，開場有沒有那行 AGENTS.md loaded 是最省事的判斷。沒看到，官方排查那節點名的頭號嫌疑犯，就是工作目錄往上某一層的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md（~/.claude/CLAUDE.md 不算）。版本太舊、/config 被設成 claude-md 或 managed-only，排在它後面。

這件事搞懂之後，下一站有兩個。一個是 .claude/rules/，它跟 AGENTS.md 是不同層的機制，而且不算數，會跟 AGENTS.md 一起載入；規則檔加上 paths，就只在 Claude 碰到符合的檔案時才載入。另一個是 /import 指令（需要 v2.1.213 以上），它會把 AGENTS.md 這類指示檔一次性複製進對應的 CLAUDE.md，順便搬 MCP servers、commands、subagents 與 skills。它跟本篇講的持續讀取是兩回事，複製過去之後兩份檔案就各走各的，選它之前要想清楚你要的是哪一種。

至於 AGENTS.md 這個標準本身這一年怎麼跟 CLAUDE.md 分岔、網域怎麼轉址，那是另一個層次的故事，8 月 26 日那篇《openai/agents.md 現在會轉址》寫過了。