這篇文章最初發表在 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 課程。