# Claude Code 現在會讀取 AGENTS.md：2.1.277 的變更 > 2026 年 9 月 18 日，Claude Code 2.1.277 新增了對 AGENTS.md 的直接支援：檔案何時會載入、如何從 4 種模式中選擇，以及如何處理匯入。 Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-agents-md-support/ Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-agents-md-support/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-041 Revision: sha256-289d7d366f8e03d21569055effef5228bbc26f20e7b495e5c273898962c0a75e 2026 年 9 月 18 日，Claude Code 2.1.277 新增了對 `AGENTS.md` 的支援。如果此功能可在工作階段和工作目錄中使用，而且目錄階層中沒有任何位於該目錄上層的 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，Claude Code 就會預設讀取 `AGENTS.md`，不必手動匯入。過去必須在 `CLAUDE.md` 中使用 `@AGENTS.md` 匯入，或建立從 `CLAUDE.md` 指向 `AGENTS.md` 的符號連結才能做到。詳情請參閱[讓多個代理程式共用一個指示檔](https://ailoot.ai/blog/zh-hant-tw/agents-md-claude-md-one-instruction-file/)一文。 如果你在同一個儲存庫中使用 Claude Code 和另外一、兩種工具，所選的 Project instructions 模式會決定 Claude Code 讀取哪些指示檔。以下說明 4 種模式各自的條件，以及從舊設定切換的步驟。 你可以在 [Ailoot 文件](https://ailoot.ai/docs/)中找到更多工具設定資料。
[Ailoot 指南](https://ailoot.ai/docs/)
## 2.1.277 版有哪些變更？
重點摘要 自 2026 年 9 月 18 日起，如果從工作資料夾往上搜尋的目錄階層中，沒有任何 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，Claude Code 就會預設讀取 `AGENTS.md`。如果存在這類檔案，Project instructions 就不會啟用自動讀取 `AGENTS.md`。從 `CLAUDE.md` 明確使用 `@AGENTS.md` 匯入仍然有效。使用者層級的 `~/.claude/CLAUDE.md`、組織管理的 `CLAUDE.md` 和 `.claude/rules/`，不受專案檔案選擇影響，會獨立載入。可透過 `/config` 切換模式。Bedrock、Vertex 或 Foundry 目前尚未提供此功能。
GitHub 上 Claude Code 專案的官方 CHANGELOG.md 如此說明：

新增 AGENTS.md 支援：在沒有 CLAUDE.md 的專案中，Claude Code 會改為讀取 AGENTS.md；可在 /config 的「Project instructions」中變更（Bedrock、Vertex 或 Foundry 尚未提供）

— Anthropic，claude-code CHANGELOG.md commit，ca02e7d，https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3
翻譯：已新增對 `AGENTS.md` 的支援。在沒有 `CLAUDE.md` 的專案中，Claude Code 現在會改為讀取 `AGENTS.md`；可在 `/config` 的「Project instructions」中切換（Bedrock、Vertex 或 Foundry 尚未提供）。 在此版本之前，工作資料夾及其上層沒有 `CLAUDE.md`、`.claude/CLAUDE.md` 和 `CLAUDE.local.md`，本身並不足以讓 Claude Code 讀取 `AGENTS.md`。必須明確匯入、建立符號連結，或使用手動 hook。現在，只要能使用此功能，代理程式就會自動讀取該檔案。 ## 哪些檔案會阻止自動讀取 AGENTS.md
重點摘要 在預設模式中，Claude Code 會檢查工作目錄及其上層的 `CLAUDE.md`、`.claude/CLAUDE.md` 和 `CLAUDE.local.md`。個人 `~/.claude/CLAUDE.md`、組織管理的 `CLAUDE.md` 和 `.claude/rules/` 檔案不會阻止讀取 `AGENTS.md`，而是會一併載入。
如果你有個人用的 `~/.claude/CLAUDE.md`，其中設定了程式碼撰寫風格，這不會阻止 Claude Code 讀取專案的 `AGENTS.md`。但在工作資料夾中，只要有任何 `CLAUDE.local.md`，即使它沒有加入 Git，只是用來記錄個人備註，也會在預設模式中阻止自動讀取 `AGENTS.md`。明確匯入仍然有效；若要直接讀取兩個檔案，就必須切換模式。 如果在 Project instructions 中選擇直接讀取模式（請參閱下方「4 種 Project instructions 模式：該選哪一種」），而且工作目錄或其上層沒有 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，Claude Code 就會在工作階段啟動時，讀取這些目錄中的每個 `AGENTS.md` 和 `.claude/AGENTS.md`。如果沒有任何阻擋檔案，文件指出互動式工作階段會顯示類似以下的行： ``` no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md ``` Claude 使用 Read 工具開啟子目錄中的檔案時，會載入該子目錄中的 `AGENTS.md`。在 `claude-md-or-agents-md` 模式中，只有當該子目錄沒有自己的 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md` 時才會載入。在 `claude-md-and-agents-md` 模式中，文件說明的一般規則是：每個目錄都會先讀取 `CLAUDE.md`，再讀取 `AGENTS.md`。`AGENTS.local.md`、`AGENTS.override.md` 和 `.agents/` 目錄中的任何檔案都不會自動讀取。 你可以在 [Ailoot 文件](https://ailoot.ai/docs/)中找到 AI 代理程式工作區設定資料，包括包含專案背景資訊的指示檔。
[Ailoot 指南](https://ailoot.ai/docs/)
## 4 種 Project instructions 模式：該選哪一種
重點摘要 在 `/config` 指令的 Project instructions 區段中，有 4 種值：`claude-md-or-agents-md`（預設，讀取兩種檔案之一）、`claude-md-and-agents-md`（同時讀取兩者）、`claude-md`（只自動讀取 `CLAUDE.md`，即使專案只有 `AGENTS.md` 也一樣），以及 `managed-only`（啟動時只讀取組織管理的 `CLAUDE.md` 和自動記憶，不讀取專案或個人檔案）。變更會從下一則傳送的訊息起生效，並套用於每個新工作階段。
表格中的模式行為說明出自 Anthropic 文件。右欄提供選擇模式的建議： | 值 | Claude Code 會讀取的內容 | 適用情況 | |----|----|----| | `claude-md-or-agents-md` | `CLAUDE.md`；若工作目錄及其上層沒有 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，則讀取 `AGENTS.md` | 儲存庫只使用兩種檔案之一，而且上層沒有阻擋檔案時，使用此預設模式 | | `claude-md-and-agents-md` | 同時讀取兩個檔案：每個目錄中先讀取 `CLAUDE.md`，再讀取 `AGENTS.md` | 你需要讓所有工具共用 `AGENTS.md`，並為 Claude 保留簡短的 `CLAUDE.md`；或是即使存在 `CLAUDE.local.md`，仍需要讀取 `AGENTS.md` | | `claude-md` | 只讀取 `CLAUDE.md`；即使只有 `AGENTS.md`，Project instructions 也不會自動讀取它（從 `CLAUDE.md` 明確使用 `@AGENTS.md` 匯入仍然有效） | `AGENTS.md` 是為其他工具撰寫，可能會讓 Claude 混淆 | | `managed-only` | 工作階段啟動時，只讀取組織管理的 `CLAUDE.md` 和自動記憶；專案、local 和使用者的 `CLAUDE.md`、`.claude/rules/` 及所有 `AGENTS.md` 檔案都不會納入初始讀取集合。不過，Claude 開啟子目錄中的檔案時，仍會在稍後載入該目錄中的 `CLAUDE.md` 和 `.claude/rules/` 檔案。此模式只限制初始讀取集合，無法完全隔離專案檔案 | 適用於重視 Claude Code 工作階段開始時會取得哪一組指示的組織，不論專案本身是否包含 `CLAUDE.md` 或 `AGENTS.md` | 你也可以不透過介面，而是在 `settings.json` 中選擇模式： ```json { "pluginConfigs": { "agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } } ``` Claude Code 會忽略 `project` 和 `local` 設定中的這個值。根據 Anthropic 文件，可在 `~/.claude/settings.json`、`--settings` 檔案或組織管理的設定中設定。 如果你已在同一個儲存庫中，為多種 AI 工具設定共用指示檔，[2.1.277 之前版本的操作說明](https://ailoot.ai/blog/zh-hant-tw/agents-md-claude-md-one-instruction-file/)會解釋 `@` 匯入的用法。這種方法現在仍然有效。 ## 為什麼 /config 中沒有 Project instructions
重點摘要 根據 Anthropic 文件，Project instructions 區段可能因為以下原因而未顯示： - Claude Code 版本低於 2.1.277。 - 工作階段未從 Anthropic 收到功能旗標，例如使用 Bedrock、其他第三方提供者，或停用了遙測功能。 - 從較舊版本安裝或更新後的第一個工作階段。如果這是唯一原因，功能會在下一個工作階段出現。只有符合所選模式的條件時，`AGENTS.md` 本身才會載入。 - 內建的 `agents-md` 外掛程式已在 `/plugin` 中停用。
先使用 `claude --version` 指令檢查版本。如果低於 2.1.277，請更新 Claude Code。如果版本符合要求，但區段仍未出現，請檢查上面列出的其他原因。功能尚未提供時，在 `CLAUDE.md` 中匯入 `@AGENTS.md` 仍是可用的替代方法。 ## 如何處理舊的 @AGENTS.md 匯入
重點摘要 你可以保留 `CLAUDE.md` 中的 `@AGENTS.md` 匯入和符號連結：在任何模式下，該檔案都不會被讀取兩次。如果保留 `CLAUDE.md`，應將文字要求「讀取 AGENTS.md」改成匯入。刪除檔案之前，請先保存所有需要的指示，並確認所選模式的條件。如果切換為直接讀取，請移除會手動輸出 `AGENTS.md` 內容的 `SessionStart` hook，否則檔案內容會重複進入上下文。之後請在新工作階段中確認載入狀況；檢查方式取決於版本和是否存在阻擋檔案。
接下來的步驟取決於舊的設定。首先，依照上一節的說明，確認目前工作階段能使用此功能。 - **`CLAUDE.md` 中有 `@AGENTS.md` 匯入。** 可以維持現狀；在任何 Project instructions 值下，Claude Code 都不會重複讀取檔案。刪除 `CLAUDE.md` 是選擇性的：透過匯入，Claude 已經能取得 `AGENTS.md` 的內容。請繼續使用 `/memory` 確認匯入載入狀況；直接詢問 Claude 指示內容，只是較不可靠的檢查方式。 - **`CLAUDE.md` 以文字要求讀取 `AGENTS.md`。** 這種要求不是匯入，本身無法確保檔案會載入。如果你要保留 `CLAUDE.md`（例如，其他工具也會讀取它），請將文字改成 `@AGENTS.md` 匯入。如果你決定完全刪除 `CLAUDE.md`，並選擇 `claude-md-or-agents-md` 模式，請先確認 `CLAUDE.md` 沒有獨有的指示，且工作目錄及其上層沒有其他 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`；否則 Claude Code 會繼續讀取剩下的檔案，而不會讀取 `AGENTS.md`。刪除後，請確認切換已生效：當不再有任何阻擋檔案時，互動式工作階段會出現 `AGENTS.md loaded` 這一行。如果保留 `CLAUDE.md` 並使用 `claude-md-and-agents-md` 模式，請在 2.1.280 版或更新版本中檢查 `/memory`。直接詢問 Claude 無法區分直接讀取和匯入。 - **`CLAUDE.md` 是指向 `AGENTS.md` 的符號連結。** 可以保留；在任何模式下都不會重複讀取。若要在 `claude-md-or-agents-md` 模式中刪除連結，請先確認必要指示已保留，而且工作目錄及其上層沒有其他 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`。請用相同方式確認載入狀況：沒有阻擋檔案時，查看工作階段啟動時的 `AGENTS.md loaded` 行，或在 2.1.280 版及更新版本中檢查 `/memory`。如果在 `claude-md-and-agents-md` 模式中保留 `CLAUDE.md`，直接詢問 Claude 只能作為較不可靠的檢查方式。沒有錯誤不代表已確認載入。 - **`SessionStart` hook 會手動輸出 `AGENTS.md` 的內容。** 直接讀取檔案時，這種 hook 會讓相同內容重複進入上下文。hook 執行期間，詢問「你的指示裡寫了什麼？」無法確認是否直接載入：Claude 可能是根據 hook 加入的文字回答。請依照以下順序切換： 1. 確認功能可用：版本為 2.1.277 或更新版本、工作階段收到功能旗標、外掛程式已啟用，而且安裝或更新後的第一個工作階段已完成。選擇直接讀取模式，不要選 `claude-md` 或 `managed-only`。使用預設模式時，也請確認沒有阻擋檔案。 2. 移除 hook。 3. 關閉工作階段並重新開啟。`SessionStart` hook 會在啟動時加入文字，所以已開啟工作階段的上下文中仍會保留那些內容。在這類工作階段中詢問 Claude 指示內容，無法確認是否直接載入。 4. 在新工作階段中確認載入狀況。2.1.280 版及更新版本會在 `/memory` 顯示 `AGENTS.md` 的路徑。在 2.1.277–2.1.279 版中，如果沒有阻擋檔案，請在啟動時尋找 `AGENTS.md loaded` 這一行：文件只針對沒有找到 `CLAUDE.md` 的情況說明了這一行。如果保留 `CLAUDE.md` 並使用 `claude-md-and-agents-md` 模式，確認方式有限：這些版本的 `/memory` 不會顯示 `AGENTS.md`，文件也沒有說明此情況會顯示載入行，而且複述指示內容無法區分直接讀取和 `CLAUDE.md` 中的 `@` 匯入。在這種情況下，請更新至 2.1.280 版或更新版本，再檢查 `/memory`。 ## 如何確認 AGENTS.md 已載入
重點摘要 從 2.1.280 版開始，透過 Project instructions 載入的 `AGENTS.md` 會顯示在 `/memory` 和 `/context` 指令的 Memory files 清單中。在 2.1.277–2.1.279 版中，即使這些指令可以正常運作，並顯示已載入的 `CLAUDE.md` 和其他記憶檔案，`AGENTS.md` 也不會顯示在其中。在這些版本中，如果沒有阻擋檔案，請檢查工作階段啟動時是否出現 `AGENTS.md loaded` 這一行。詢問 Claude 指示的內容只能算是較不可靠的檢查方式：答案無法區分直接讀取和 `@` 匯入，也可能根據 `SessionStart` hook 加入的文字作答。因此，只有在移除這類 hook 並開啟新工作階段後，才適合提出這個問題。
它和一般的 `CLAUDE.md` 另有兩項差異：這類 `AGENTS.md` 不會觸發 `InstructionsLoaded` hooks（透過 `CLAUDE.md` 的 `@` 語法匯入，或由 `CLAUDE.md` 符號連結連接的 `AGENTS.md` 則會觸發）；使用 `--add-dir` 旗標和 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` 變數加入的目錄，只會載入該目錄的 `CLAUDE.md`，不會包含其中的 `AGENTS.md`。 如果你需要檢視大型專案指示檔的內容，請參閱[如何設定 CLAUDE.md 而不讓它變得臃腫](https://ailoot.ai/blog/zh-hant-tw/claude-md-template/)的個別分析。該文說明指示的結構；上述內容則說明 `AGENTS.md` 的載入條件。工作階段間的工作筆記，請參閱[在 Claude Code 中建立第二大腦](https://ailoot.ai/blog/zh-hant-tw/claude-code-second-brain/)的分析，了解如何在專案指示上疊加個人記憶。 ## 接下來 此功能於 2026 年 9 月 18 日隨 2.1.277 版推出。Anthropic 可能會在後續版本中釐清各模式的詳細資訊，因此在變更重要專案的設定之前，請先將本文與目前的 `/config` 和官方變更記錄核對。
### 來源 - [Claude Code：GitHub 上包含 2.1.277 項目的 CHANGELOG.md commit（2026 年 9 月 18 日）](https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3) - [Claude Code 文件：Claude 如何記住你的專案——AGENTS.md 章節](https://code.claude.com/docs/en/memory)
[Ailoot 指南](https://ailoot.ai/docs/)
[前往 Ailoot](https://ailoot.ai/)
## 常見問題：Claude Code 現在會讀取 AGENTS.md：2.1.277 的變更 ### 檔案存在，為什麼 AGENTS.md 還是沒有載入？ 預設模式中，工作目錄或上層若有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，就會阻擋自動選取 AGENTS.md。另須檢查 Claude Code 版本、功能可用性及 /config 的 Project instructions 模式。 ### 移除手動 hook 後，如何驗證直接載入？ 開新工作階段，排除舊 SessionStart 輸出。2.1.280 以上查看 /memory 或 /context 的 Memory files；2.1.277–2.1.279 則在沒有阻擋 CLAUDE.md 時看啟動載入行。只聽 Claude 轉述內容，證據很弱。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。