跳到主要內容
maxstudioNews
AI 自動化DEV Community (Claude Code)約 11 分鐘

Claude Code 指令檔解析:CLAUDE.md 與 AGENTS.md 的優先順序與應用指南

本文深入探討 Claude Code 如何讀取其指令檔,主要比較 CLAUDE.md 與 AGENTS.md 兩種格式。Claude Code 會優先讀取 CLAUDE.md,若無此檔案才會退而求其次讀取 AGENTS.md,但 CLAUDE.local.md 的存在會悄悄停用 AGENTS.md 的讀取。文章也提供在多種 AI 程式碼工具之間共用指令設定的最佳實踐。

Claude Code 指令檔解析:CLAUDE.md 與 AGENTS.md 的優先順序與應用指南
圖片來源:DEV Community (Claude Code)

這篇文章最初發表在 DevToolHub 上。Claude Code 會優先讀取 CLAUDE.md 檔案,只有當 CLAUDE.md 不存在時,才會改為讀取 AGENTS.md。這條規則解決了大多數關於 CLAUDE.md 與 AGENTS.md 的疑問。

如果您也使用 Codex、Cursor 或 Copilot 等工具,建議將共用規則放在 AGENTS.md 中,然後在 CLAUDE.md 檔案中加入 @AGENTS.md 來導入它。我使用 Claude Code 2.1.322 版本進行了測試,在每個檔案中放入一個獨特的代碼詞,並在一次性資料夾中執行 claude -p,然後要求它列出所有已載入指令中的代碼詞。

結果與文件相符,但有一個大多數指南都忽略的細節:CLAUDE.local.md 會悄悄地停用 AGENTS.md 的讀取。

CLAUDE.md 與 AGENTS.md 有何不同?CLAUDE.md 是 Claude Code 自己的指令檔案。AGENTS.md 則是一種開放的純 Markdown 格式,許多程式碼工具都能讀取,且沒有必填欄位。實際上,兩者都包含相同類型的內容:建置指令、程式碼風格和專案規則。

下表比較了這兩種檔案:

| 特性 | CLAUDE.md | AGENTS.md |

|---|---|---|

| 讀取工具 | Claude Code | Codex、Cursor、Windsurf、Copilot 的程式碼代理等;Claude Code 從 v2.1.277 版本開始讀取 |

| 格式 | 帶有 @path 導入的 Markdown | 純 Markdown,可使用任何標題 |

| 個人、未提交檔案 | CLAUDE.local.md | 無 |

| 路徑範圍規則 | .claude/rules/ | Claude 專屬功能,不屬於格式的一部分 |

| InstructionsLoaded 鉤子 | 觸發 | 當 Claude 透過設定讀取時不會觸發 |

工具列表來自 AGENTS.md 網站,該網站也提到 Aider 和 Gemini CLI 需要設定才能讀取它。Claude Code 的欄位資訊則來自記憶體文件。

當 CLAUDE.md 和 AGENTS.md 都存在時,Claude Code 會載入哪個?它會載入 CLAUDE.md 並忽略 AGENTS.md。預設情況下,只有當您的工作目錄或其上層目錄中沒有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 時,Claude 才會讀取 AGENTS.md。以下是我觀察到的結果:

每個資料夾都包含帶有不同代碼詞的檔案,因此右欄顯示了 Claude 報告的內容。

| 資料夾中的檔案 | Claude 報告的代碼詞 |

|---|---|

| 僅 AGENTS.md | AGENTS.md 代碼詞 |

| AGENTS.md 和 CLAUDE.md | 僅 CLAUDE.md 代碼詞 |

| 包含 @AGENTS.md 的 CLAUDE.md | 兩個代碼詞 |

| AGENTS.md 和 CLAUDE.local.md | 僅 CLAUDE.local.md 代碼詞 |

| CLAUDE.md 作為 AGENTS.md 的符號連結 | 一個代碼詞,載入一次 |

第四行是一個陷阱。CLAUDE.local.md 在此檢查中被視為 CLAUDE.md,因此新增一個用於個人筆記的 CLAUDE.local.md 會阻止 Claude 讀取您的 AGENTS.md。您的 ~/.claude/CLAUDE.md、受管理的 CLAUDE.md 和 .claude/rules/ 檔案則不在此限,它們會繼續與 AGENTS.md 一起載入。

在互動式會話中,您可以確認這一點。當 AGENTS.md 是正在使用的檔案時,Claude 會顯示類似「no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md」的訊息。

如何在不同工具之間共用 CLAUDE.md 與 AGENTS.md 設定?選擇一個真實來源,然後將另一個檔案指向它。您有四種選擇,文件涵蓋了所有這些選項。

1. 僅使用 AGENTS.md。在 Claude Code v2.1.277 或更高版本上,這無需額外設定即可運作。在此版本之前,或如果內建外掛程式被停用,Claude 只會讀取 CLAUDE.md 檔案。

2. 從 CLAUDE.md 導入。建立一個以導入開頭的 CLAUDE.md,然後在下方添加 Claude 專用的筆記,例如:@AGENTS.md ## Claude Code - 對於涉及三個以上檔案的變更,請使用計畫模式。 我測試過這個方法,兩個代碼詞都載入了。

文件指出,當 CLAUDE.md 導入 AGENTS.md 時,Claude 絕不會重複讀取 AGENTS.md。它也適用於舊版本。

3. 將一個檔案符號連結到另一個。這只會在目前資料夾中建立連結,如果 CLAUDE.md 已存在,ln 指令會失敗:ln -s AGENTS.md CLAUDE.md。在我的測試中,內容只載入了一次。但您無法保留 Claude 專用的筆記,因為兩個名稱指向同一個檔案。

4. 有意地同時載入兩者。開啟 /config,找到「專案指令 (Project instructions)」,然後選擇 claude-md-and-agents-md。我沒有測試這個設定。我個人使用選項 2。它適用於所有版本,其他工具會看到一個乾淨的 AGENTS.md,而 Claude 專用的筆記也不會干擾它們。

子目錄中的 CLAUDE.md 檔案如何載入?Claude 在啟動時會載入您的工作目錄及其上層目錄中的 CLAUDE.md。子目錄中的 CLAUDE.md 則會等到 Claude 讀取該資料夾中的檔案後才載入。我使用一個根檔案和一個 sub/CLAUDE.md 進行了檢查。

一開始,Claude 只報告了根目錄的代碼詞。然後我讓它讀取 sub/notes.txt,它就報告了兩個代碼詞。這在單一儲存庫 (monorepo) 中很重要,因為團隊資料夾中的規則在 Claude 實際在該資料夾中工作之前不會產生任何成本。

如果來自另一個團隊的祖先檔案妨礙了您,claudeMdExcludes 設定可以透過路徑或全域模式跳過它。

CLAUDE.md 或 AGENTS.md 檔案中應該包含什麼?編寫可以驗證的指令,並將檔案保持在 200 行以下。較長的檔案會使用更多的上下文,因此 Claude 遵循它們的效果會較差。導入可以組織長檔案,但不會縮小它,因為導入的檔案會與導入它們的檔案一起載入。比較文件中這些對比的範例。具體版本才是應該編寫的:

  • 「使用 2 個空格縮排」而不是「正確格式化程式碼」
  • 「在提交前執行 npm test」而不是「測試您的變更」
  • 「API 處理器位於 src/api/handlers/ 」而不是「保持檔案有條理」

一個簡短的起點看起來像這樣:

# 專案筆記

## 指令

- 安裝:npm ci`

- 測試單一檔案:npx vitest run path/to/file.test.ts`

- 提交前檢查:npm run lint`

## 慣例

- API 處理器位於 src/api/handlers/`。

- 使用 2 個空格縮排。

## 不要

- 不要編輯 generated/ 下的檔案。請改為執行 npm run codegen。

要開始,請執行 /init,Claude 會根據您的程式碼庫編寫初稿。還有四點值得了解:

這只是上下文,而非強制執行。Claude 仍然可以忽略某一行。要絕對阻止某個動作,請使用 PreToolUse 鉤子或 permissions.deny 規則。註解是免費的。區塊級的 HTML 註解在檔案到達 Claude 之前會被移除,因此您可以保留維護者筆記。

冗長的程序應放在其他地方。將多步驟工作流程移至技能 (Skill) 中,如我們的「代理技能指南」所述。稽核檔案。/doctor prompt-audit (v2.1.283 或更高版本) 會標記過時或衝突的指令並提出編輯建議。我沒有執行它。

有關安裝和首次執行步驟,請參閱 Claude Code 設定指南和快速入門指南。Claude Code 也可在瀏覽器中執行,我們的「Claude Code 網頁版指南」對此有所涵蓋。

CLAUDE.md 與 AGENTS.md:您應該使用哪一個?如果 Claude Code 是您唯一的代理工具,請使用 CLAUDE.md。如果您的團隊混合使用多種工具,請使用 AGENTS.md 加上一行導入語句的 CLAUDE.md。不要維護兩份相同的規則。

  • 僅使用 Claude Code:CLAUDE.md。您還可以使用 CLAUDE.local.md 和 .claude/rules/。
  • 兩個或更多代理工具:AGENTS.md 用於共用規則,以及一個包含 @AGENTS.md 的 CLAUDE.md 用於 Claude 的額外設定。
  • 您已經有 AGENTS.md 且 Claude Code 版本為 2.1.277 或更高:無需做任何事。只是不要添加 CLAUDE.local.md,除非您更改了「專案指令 (Project instructions)」設定。
  • 一個舊的解決方法:一個只用文字說明「讀取 AGENTS.md」的 CLAUDE.md 比導入語句弱,因為 Claude 必須決定是否開啟該檔案。請將該句子替換為 @AGENTS.md。

我未測試的內容:我僅在 Claude Code 2.1.322 版本上使用 claude -p 測試了檔案載入。除此之外,我沒有檢查 Claude 在載入指令後遵循指令的程度。其他工具讀取 AGENTS.md 的情況也未經測試,因此該列表來自 AGENTS.md 網站。

我跳過了路徑範圍規則、受管政策檔案、/init 輸出、自動記憶體、claude-md-and-agents-md 設定以及 2.1.277 之前的任何版本。

常見問題:

問:Claude Code 會讀取 AGENTS.md 嗎?

答:是的,從 v2.1.277 版本開始,但僅限於您的工作目錄或其上層目錄中沒有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 的情況。如果這些檔案中的任何一個存在,Claude 會讀取它們並跳過 AGENTS.md,除非您導入它或更改「專案指令 (Project instructions)」設定。

問:我可以將 CLAUDE.md 符號連結到 AGENTS.md 嗎?

答:可以。在我的測試中,Claude 載入了一次內容。通常 @AGENTS.md 導入會更好,因為它允許您在 CLAUDE.md 檔案中添加 Claude 專用的筆記。

問:CLAUDE.md 檔案應該放在哪裡?

答:對於專案,請使用 ./CLAUDE.md 或 ./.claude/CLAUDE.md。對於所有專案的個人設定,請使用 ~/.claude/CLAUDE.md。對於單一專案中的個人筆記,請使用 ./CLAUDE.local.md 並將其添加到 .gitignore。

問:檔案應該多長?

答:每個檔案應在 200 行以下。超過此限制,Claude 遵循它的可靠性會降低,因此請將部分程式碼庫規則移至 .claude/rules/ 或子目錄的 CLAUDE.md 中。

問:Claude 會一直遵循它嗎?

答:不會。文件稱這些檔案為上下文,而非強制配置。對於任何絕對不能發生的事情,請使用鉤子或權限規則。

快速摘要:

  • 當 CLAUDE.md 和 AGENTS.md 都存在時,Claude Code 會載入 CLAUDE.md 並忽略 AGENTS.md。
  • 僅有 AGENTS.md 時,Claude Code 2.1.277 或更高版本會自動讀取它。
  • CLAUDE.local.md 被視為 CLAUDE.md,並會停用 AGENTS.md 的讀取。
  • CLAUDE.md 內部包含 @AGENTS.md 會同時載入兩者,而符號連結只會載入一次內容。
  • 子目錄檔案只有在 Claude 讀取該資料夾中的檔案後才會載入。
  • 將檔案保持在 200 行以下,並使用鉤子來處理必須強制執行的規則。

檢查您的儲存庫中 CLAUDE.md 與 AGENTS.md 的答案只需一分鐘:如果它同時有 AGENTS.md 和 CLAUDE.local.md,那麼 Claude 就沒有讀取第一個檔案。如需這些工具的結構化練習,請參閱免費的 Anthropic Academy 課程。

Share

覺得值得一看?分享給朋友。

以上為 AI 自動翻譯導讀。原文版權歸 DEV Community (Claude Code) 所有, 建議透過「閱讀原文」前往原始網站,以取得最完整資訊並支持原作者。

Newsletter

不用每天追,AI 重點每週寄給你

43 個來源、每 2 小時更新,太多看不完。電子報每週挑最值得看的幾則,附上 Max 的看法。

每週一封。Email 只用來寄電子報,每封信都能一鍵退訂。