CLAUDE.md 怎麼寫：最佳實踐、模板與 AGENTS.md 的區別

本文根據 Claude Code 官方文檔（記憶 / 最佳實踐）、Anthropic 官方網誌、AGENTS.md 官網和 OpenAI Codex 官方文檔整理，核對日期 2026-10-07。圖片為 Claude Code 官方文檔配圖和 AGENTS.md 官網首頁截圖，圖下註明出處。

適用於誰

• 已經在用 Claude Code（入門可先看本站《Claude Code 中文入門教學》），跑過 /init，但不知道生成的 CLAUDE.md 該怎麼改的人；
• 發現 Claude「總是記不住項目規矩」、同一個錯誤反覆犯的人；
• 團隊裏有人用 Claude Code、有人用 Codex 或 Cursor，想只維護一份說明文件的人。

結論先說

1. CLAUDE.md 是寫給 Claude 的項目說明書，每次會話開始時自動讀入。它是「上下文」，不是強制配置：要絕對禁止某個操作，用權限規則或 hooks。
2. 短、具體、可驗證：官方建議每個文件控制在 200 行以內；每寫一行都問自己「刪掉這行，Claude 會不會犯錯？」不會就刪。
3. 只寫 Claude 自己看代碼推不出來的東西：構建 / 測試命令、和預設習慣不同的代碼規範、分支和提交約定、環境上的坑。
4. AGENTS.md 是跨工具的開放格式，Codex、Cursor、Gemini CLI 等都支持。2026 年的 Claude Code（v2.1.277 起）在倉庫裏沒有 CLAUDE.md 時會直接讀 AGENTS.md；兩個都有時預設只讀 CLAUDE.md。
5. 兩個都要用時：公共內容寫進 AGENTS.md，CLAUDE.md 第一行寫 @AGENTS.md 導入，下面只補 Claude 專屬的內容。

一、CLAUDE.md 放在哪：四個位置

加載規則要點（官方文檔）：

• 啟動時會讀取當前目錄以及所有上級目錄裏的 CLAUDE.md / CLAUDE.local.md，內容是拼接而不是互相覆蓋，離你啟動目錄越近的越晚讀到；同一層裏 CLAUDE.local.md 排在 CLAUDE.md 後面。
• 子目錄裏的 CLAUDE.md 不在啟動時加載，Claude 讀寫那個子目錄裏的文件時才會帶上。
• 塊級 HTML 註釋 <!-- ... --> 會在注入前被去掉，適合給人類維護者留備註而不佔上下文。
• 想確認讀到了哪些文件：會話裏運行 /context，看「Memory files」一欄。

圖片來源：Claude Code 官方文檔《Extend Claude Code》

這張圖也說明了為什麼 CLAUDE.md 要短：它每一輪請求都會帶上。只在部分場景才需要的長流程，應該寫成技能（Skill），或者放進按路徑生效的規則裏。

二、該寫什麼、不該寫什麼

官方最佳實踐給出的對照（整理翻譯）：

寫法上的四條建議：

• 寫成能檢查的句子：寫「用 2 個空格縮進」而不是「代碼格式要規範」；寫「提交前運行 npm test」而不是「記得測試」；寫「接口處理函數放在 src/api/handlers/」而不是「文件要組織好」。
• 用標題和列表分組，比大段文字更容易被遵守。
• 避免互相矛盾：兩條規則衝突時，Claude 可能隨便選一條。定期檢查根目錄、子目錄 CLAUDE.md 和 .claude/rules/ 有沒有打架。
• 強調要剋制：某一條總被忽略，可以只在那一行加「IMPORTANT」；到處都強調，等於都沒強調。

什麼時候往裏加內容？官方給的信號是：Claude 第二次犯同一個錯誤；代碼審查發現了它本該知道的項目約定；你在新會話裏又打了一遍上次打過的糾正；新同事也需要知道同樣的背景。幫助中心還建議「兩次原則」：同一件事糾正到第二次再寫進去，第一次往往只是偶然。

不要把密鑰、密碼、數據庫連接串寫進 CLAUDE.md。Anthropic 官方網誌提醒，它會進入系統提示詞，提交到倉庫時應當當作可能公開的文檔來對待。

三、可複製的 CLAUDE.md 模板

下面是按官方建議整理的骨架，方括號裏換成你項目的實際內容，用不上的小節直接刪掉：

markdown
# 項目說明
[一句話：這是什麼項目、給誰用]。技術棧：[框架 / 語言 / 數據庫]。

## 常用命令
- 安裝依賴：`[pnpm install]`
- 本地啟動：`[pnpm dev]`
- 運行單個測試：`[pnpm test -- path/to/file]`（優先跑單個測試，不要每次跑全量）
- 類型檢查：`[pnpm typecheck]`，一組改動完成後必須通過

## 目錄約定
- `[src/api/]`：接口；`[src/lib/]`：工具函數；`[src/components/]`：介面組件
- 新增數據庫字段先改 `[prisma/schema.prisma]`，再生成遷移

## 代碼規範（只寫和預設習慣不同的）
- [使用 ES Module（import/export），不用 require]
- [金額統一用「分」為單位的整數存儲]

## 工作流程
- 改動超過 3 個文件時，先列出要改哪些文件、每個文件改什麼，確認後再動手
- 提交資訊格式：[feat: / fix: 開頭，中文描述]
- 不要直接推送到 [main] 分支

## 已知的坑
- [本地需要環境變量 XXX_URL，示例見 .env.example]
- IMPORTANT: [不要修改 legacy/ 目錄下的任何文件]

## 參考
- 接口約定見 @docs/api-conventions.md

用法提示：

• 先在項目裏運行 /init 讓 Claude 生成初稿（已有 CLAUDE.md 時它會提改進建議而不是覆蓋），再對照模板刪減補充。設定環境變量 CLAUDE_CODE_NEW_INIT=1 後，/init 會改為多輪問答式，可以一併設定技能和 hooks。
• 改完後開新會話，用 /context 確認已加載，再觀察 Claude 的行為有沒有真的改變——官方建議把 CLAUDE.md 當代碼對待：出問題時回頭看、定期刪減。
• v2.1.283 及以後的版本可以運行 /doctor prompt-audit，讓 Claude 檢查指令文件裏過時、矛盾或引用了不存在文件的內容，只出報告，不會擅自改文件。

四、文件變長了怎麼辦

• @ 導入：在 CLAUDE.md 裏寫 @docs/git-instructions.md 就會把那個文件一起加載。相對路徑以「寫導入的那個文件」為基準，最多嵌套 4 層；放在反引號裏的 ` @README ` 不會被導入。注意導入只是方便組織，被導入的文件同樣在啟動時加載，不會省上下文。
• .claude/rules/ 按主題拆分：每個主題一個 .md 文件（如 testing.md、security.md）。在文件開頭寫 paths 字段，就只在 Claude 讀寫匹配的文件時才加載，例如：

markdown
---
paths:
  - "src/api/**/*.ts"
---
# 接口開發規則
- 所有接口必須做參數校驗

• 多步驟流程改成技能：比如「發佈流程」「寫週報的格式」，做成 Skill 只在用到時加載。
• 別和自動記憶混淆：Claude Code 還會自己記筆記（自動記憶，存在 ~/.claude/projects/<項目>/memory/，索引文件 MEMORY.md 每次只加載前 200 行或 25KB）。CLAUDE.md 是你寫的規則，自動記憶是 Claude 從你的糾正裏學到的東西，兩者都在會話開始時加載，用 /memory 可以查看和編輯。

五、AGENTS.md 是什麼

AGENTS.md 是一個面向 AI 編程代理的開放格式，官網的說法是「給代理看的 README」：README 寫給人看，AGENTS.md 放代理需要的構建步驟、測試命令和代碼約定。它由 OpenAI Codex、Amp、Google Jules、Cursor、Factory 等共同推動，官網稱已被 6 萬多個開源項目採用，現由 Linux 基金會旗下的 Agentic AI Foundation 託管。

圖片來源：AGENTS.md 官網（首頁截圖）

它沒有必填字段，就是普通 Markdown。常見小節：項目概覽、構建和測試命令、代碼風格、測試說明、安全注意事項、提交和 PR 規範。大型 monorepo 可以在每個子包裏再放一個 AGENTS.md，代理會讀離被修改文件最近的那個。

Codex 怎麼讀 AGENTS.md（OpenAI 官方文檔）：

1. 全局：~/.codex/AGENTS.md（有 AGENTS.override.md 時優先用它）；
2. 項目：從 Git 根目錄往下走到當前目錄，每一層依次找 AGENTS.override.md、AGENTS.md，以及你在配置裏設定的備用文件名，每層最多取一個；
3. 從上到下拼接，越靠近當前目錄的越靠後、優先級越高；合計超過 project_doc_max_bytes（預設 32 KiB）就不再追加。

Codex CLI 裏運行 /init 會生成 AGENTS.md（見本站《Codex 入門教學》）。

六、CLAUDE.md 和 AGENTS.md 的區別

Claude Code 讀取 AGENTS.md 的預設規則（官方文檔）：

• 倉庫裏只有 AGENTS.md、當前目錄及以上都沒有 CLAUDE.md / CLAUDE.local.md → 讀 AGENTS.md，啟動時會提示「no CLAUDE.md found; AGENTS.md loaded」；
• AGENTS.md 和 CLAUDE.md 都有 → 預設只讀 CLAUDE.md；
• 注意：~/.claude/CLAUDE.md 和 .claude/rules/ 不影響這個判斷，但只要項目裏加了一個 CLAUDE.local.md，Claude 就不再讀 AGENTS.md 了。

想改預設行為，在會話裏運行 /config，把「Project instructions」設為：claude-md-and-agents-md（兩個都讀）、claude-md（只讀 CLAUDE.md）或 managed-only。

七、一個倉庫裏怎麼讓兩者共存

官方推薦的做法：把團隊共用的內容放進 AGENTS.md，然後在旁邊的 CLAUDE.md 裏這樣寫：

markdown
@AGENTS.md

## Claude Code 專屬
- 修改 `src/billing/` 下的代碼前先進入 plan 模式出方案

這樣 Claude 先讀 AGENTS.md，再讀下面的補充，而且保留這個導入不會導致重複讀取。如果不需要任何 Claude 專屬內容，也可以用符號連結 ln -s AGENTS.md CLAUDE.md，但官方提醒：只要有人在 Windows 上克隆倉庫，就改用 @AGENTS.md 導入——Windows 創建符號連結需要管理員權限或開發者模式，Git 預設還會把它檢出成一個只有一行字的普通文件。

已經在 CLAUDE.md 裏用文字寫「請去讀 AGENTS.md」的，建議改成 @AGENTS.md 導入：文字提示只有在 Claude 自己決定打開文件時才生效。從其他工具遷移時，/init 會參考 Cursor 規則（.cursor/rules/、.cursorrules）和 .github/copilot-instructions.md；/import（v2.1.213 起）可以把 Codex 等工具的配置一次性導入。

常見問題

Q：CLAUDE.md 寫了，Claude 還是不照做？

官方給的排查方向：文件太長導致規則被淹沒；措辭含糊（Claude 會就文件裏已有答案的問題反問你）；多個文件互相矛盾。先精簡，再把關鍵規則寫成可檢查的句子。必須強制執行的（比如禁止刪某個目錄），改用權限規則或 PreToolUse hook。

Q：CLAUDE.md 有長度上限嗎？

官方建議每個文件 200 行以內；Claude Code 能完整加載最大 4 MiB 的 CLAUDE.md，再大就跳過，但越短遵守得越好。

Q：中文寫可以嗎？

官方沒有語言要求，CLAUDE.md 就是普通 Markdown。命令、路徑、文件名保持原樣即可。

Q：Codex 能讀 CLAUDE.md 嗎？

Codex 預設找的是 AGENTS.md。官方文檔提供了 project_doc_fallback_filenames 配置，可以把其他文件名加進備用列表；更省事的做法還是以 AGENTS.md 為主、CLAUDE.md 導入它。

參考資料

• Claude Code：CLAUDE.md、AGENTS.md 與自動記憶（官方）：https://code.claude.com/docs/en/memory
• Claude Code 最佳實踐（官方）：https://code.claude.com/docs/en/best-practices
• Claude Code 擴展功能概覽（官方，含上下文加載示意圖）：https://code.claude.com/docs/en/features-overview
• Claude Code 模型、用量與 CLAUDE.md 精簡建議（官方幫助中心）：https://support.claude.com/en/articles/14552983-models-usage-and-limits-in-claude-code
• Anthropic 網誌《Using CLAUDE.md files》：https://claude.com/blog/using-claude-md-files
• AGENTS.md 官網：https://agents.md/
• OpenAI Codex：Custom instructions with AGENTS.md（官方）：https://learn.chatgpt.com/docs/agent-configuration/agents-md