Claude Code 現在會讀取 AGENTS.md：2.1.277 的變更

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 的符號連結才能做到。詳情請參閱讓多個代理程式共用一個指示檔一文。

如果你在同一個儲存庫中使用 Claude Code 和另外一、兩種工具，所選的 Project instructions 模式會決定 Claude Code 讀取哪些指示檔。以下說明 4 種模式各自的條件，以及從舊設定切換的步驟。

你可以在 Ailoot 文件中找到更多工具設定資料。

2.1.277 版有哪些變更？#

GitHub 上 Claude Code 專案的官方 CHANGELOG.md 如此說明：

翻譯：已新增對 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/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 文件中找到 AI 代理程式工作區設定資料，包括包含專案背景資訊的指示檔。

4 種 Project instructions 模式：該選哪一種#

表格中的模式行為說明出自 Anthropic 文件。右欄提供選擇模式的建議：

你也可以不透過介面，而是在 settings.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 之前版本的操作說明會解釋 @ 匯入的用法。這種方法現在仍然有效。

為什麼 /config 中沒有 Project instructions#

先使用 claude --version 指令檢查版本。如果低於 2.1.277，請更新 Claude Code。如果版本符合要求，但區段仍未出現，請檢查上面列出的其他原因。功能尚未提供時，在 CLAUDE.md 中匯入 @AGENTS.md 仍是可用的替代方法。

如何處理舊的 @AGENTS.md 匯入#

接下來的步驟取決於舊的設定。首先，依照上一節的說明，確認目前工作階段能使用此功能。

• 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 已載入#

它和一般的 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 而不讓它變得臃腫的個別分析。該文說明指示的結構；上述內容則說明 AGENTS.md 的載入條件。工作階段間的工作筆記，請參閱在 Claude Code 中建立第二大腦的分析，了解如何在專案指示上疊加個人記憶。

接下來#

此功能於 2026 年 9 月 18 日隨 2.1.277 版推出。Anthropic 可能會在後續版本中釐清各模式的詳細資訊，因此在變更重要專案的設定之前，請先將本文與目前的 /config 和官方變更記錄核對。