DotMD
下載 Mac 版

CLAUDE.md 與 AGENTS.md：哪個代理程式讀哪個檔案。

兩者都是寫給程式碼代理程式的 Markdown 指示檔，內容重疊很多，所以大家常會不小心兩個都留著。這裡說明各自的用途、誰會讀它，以及如何避免維護兩份副本。

下載 Mac 版

需要 macOS 14 或以上版本。閱讀免費；編輯與審閱為一次付費。

快速解答

CLAUDE.md 是 Claude Code 讀取的指示檔。AGENTS.md 是開放格式，Codex、Cursor 和許多其他代理程式都會讀取。如果你同時使用 Claude Code 和其他代理程式，請把共用規則放在 AGENTS.md，並在 CLAUDE.md 最上方寫 @AGENTS.md，Claude 專用的指示寫在它下面。

@AGENTS.md

## Claude Code

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

·

兩個檔案各是什麼

兩者都是純 Markdown，代理程式在工作階段開始時載入它的情境。你寫建置與測試指令、程式碼風格、專案結構，以及像「不要編輯產生的檔案」這樣的規則。它們是指示，不是強制執行的設定：代理程式把它們當作指引。

  • CLAUDE.md 專屬於 Claude Code。它可以放在專案根目錄（./CLAUDE.md 或 ./.claude/CLAUDE.md）、放在 ~/.claude/CLAUDE.md 供你所有專案使用，也可以放在子資料夾中。CLAUDE.local.md 則存放單一專案的私人備註。
  • AGENTS.md 是 agents.md 上說明的開放格式，是寫給代理程式的 README。Codex、Cursor、GitHub Copilot 的程式碼代理程式、Gemini CLI、Zed 等許多工具都會讀取。在 monorepo 中，子資料夾的 AGENTS.md 套用於該部分，並以最近的檔案為準。

內容是同一類的東西，差別在於哪個工具會讀取該檔案。

Claude Code 如何處理 AGENTS.md

Claude Code 的文件針對 2.1.277 版以後，描述了三種情況：

  • 專案中只有 AGENTS.md，沒有 CLAUDE.md：Claude Code 會讀取 AGENTS.md。
  • 專案中兩個檔案都有：Claude Code 只讀取 CLAUDE.md 檔案。
  • CLAUDE.md 以 @AGENTS.md 匯入 AGENTS.md：Claude 讀取 CLAUDE.md，並一併包含 AGENTS.md。

第二種情況最讓人意外。如果你在已有 AGENTS.md 的儲存庫加入 CLAUDE.md，即使很小，除非 CLAUDE.md 匯入它，Claude 就不會再讀取 AGENTS.md。CLAUDE.local.md 也一樣。較舊版本的 Claude Code 只讀取 CLAUDE.md，這就是匯入仍然是安全選擇的原因。文件中也說明了 /config 裡的 Project instructions 設定，可以讓 Claude 同時讀取兩個檔案。

只維護一份指示

選一個檔案作為唯一的資料來源。文件中記載了兩種做法：

  1. 在 CLAUDE.md 中匯入 AGENTS.md

    在 AGENTS.md 旁邊建立 CLAUDE.md，第一行寫 @AGENTS.md，然後在下面加上 Claude 專用的指示。匯入使用 @path 語法，相對路徑從包含它的檔案開始解析，被匯入的檔案還可以再匯入其他檔案，最深四層。

  2. 把 CLAUDE.md 做成 AGENTS.md 的符號連結

    如果沒有 Claude 專用的內容要加，執行 ln -s AGENTS.md CLAUDE.md。文件警告說，Claude 的編輯工具不會透過符號連結寫入，而且在 Windows 上，已提交的符號連結可能會被檢出為只有一行的文字檔，所以對共用儲存庫來說，匯入是比較安全的選擇。

避免第三種做法：在 CLAUDE.md 裡用文字寫「請閱讀 AGENTS.md」。Claude 只有在決定開啟那個檔案時才會看到，而匯入則每次都會載入。

共用的 AGENTS.md

把任何代理程式都需要的內容放進 AGENTS.md：

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

保持簡短而具體。Claude Code 文件建議每個 CLAUDE.md 維持在約 200 行以內，因為較長的檔案會佔用情境，也較不容易被可靠地遵循。

常見錯誤

  • 兩個檔案各走各的。一份更新了，另一份沒有。請使用匯入。
  • 加了 CLAUDE.md 卻讓 AGENTS.md 失效。見上文：把它匯入。
  • 在任一檔案中放入機密。它們會被提交，並載入每個工作階段。
  • 模糊的規則。「寫乾淨的程式碼」沒有任何作用。「說完成之前先執行 npm test」才有用。
  • 規則互相矛盾：父資料夾的檔案與子資料夾的檔案說法不一。

閱讀與審查這些檔案

兩者都是一般的 Markdown，因此 DotMD 可以開啟 CLAUDE.md 與 AGENTS.md，如同任何 .md 檔案，提供大綱與每次變更的歷史，並顯示代理程式在其中改了什麼。閱讀免費。另請參閱搭配 DotMD 使用的 Claude Code 與 Codex。

關於 CLAUDE.md 與 AGENTS.md 的常見問題

CLAUDE.md 與 AGENTS.md 有什麼差別？

CLAUDE.md 是 Claude Code 的指示檔。AGENTS.md 是開放、與工具無關的格式，Codex、Cursor 等許多代理程式都會讀取。內容相似，差別在讀取的工具。

Claude Code 會讀取 AGENTS.md 嗎？

較新的版本會，但只在你的工作目錄或其上層沒有 CLAUDE.md 時。如果兩者都有，它會讀取 CLAUDE.md 檔案，所以請在 CLAUDE.md 中以 @AGENTS.md 匯入 AGENTS.md。

我該同時保留 CLAUDE.md 與 AGENTS.md 嗎？

如果你同時使用 Claude Code 和其他代理程式，是的：把共用指示放在 AGENTS.md，讓 CLAUDE.md 匯入它，再加上 Claude 專用的內容。

CLAUDE.md 要放在哪裡？

專案請放在專案根目錄或 .claude/，所有專案共用請放在 ~/.claude/CLAUDE.md，不提交的私人備註則放在 CLAUDE.local.md。

更多問題

其他文章

PRD 範本 AI 規格審查檢查表

指南

CLAUDE.md 與 AGENTS.md Claude Code Codex Cursor