用好 CoreCode

CLAUDE.md 怎麼寫

最後更新：2026 年 10 月 27 日

CLAUDE.md 是寫給 Claude Code 的專案說明，每次工作階段開始時都會讀一遍。寫得好，Claude 少犯重複的錯；寫得長而亂，它每一輪都在浪費上下文。這一頁按 Anthropic 的 官方說明 整理，加上它對花費的影響。

CLAUDE.md 是什麼

一個純文字的 Markdown 檔案，寫著 Claude 在這個專案裡應該知道的事：怎麼建置和測試、程式碼約定、目錄結構、“總是要這樣做”的規則。Claude Code 每次啟動工作階段都會讀它，把它當作上下文。

它不是強制設定。規則寫得越具體、越簡潔，Claude 越穩定地遵守；但要“無論如何都不許做”的事，比如不許改某個目錄，應該用 PreToolUse hook 攔截。

另外 Claude Code 還有一套“自動記憶”：你糾正過它的事，它會自己記下來，存在 ~/.claude/projects/<專案>/memory/。CLAUDE.md 是你寫的規則，自動記憶是它學到的經驗，兩者每次工作階段都會載入。

放在哪

啟動時，Claude Code 讀取當前目錄和它所有上級目錄裡的 CLAUDE.md，內容按從上到下的順序拼在一起，越靠近當前目錄的越後讀。子目錄裡的 CLAUDE.md 不在啟動時讀，而是等 Claude 讀寫那個子目錄裡的檔案時才載入。

從哪開始

在專案裡執行 /init。Claude 會分析程式碼庫，生成一份包含建置命令、測試方法和專案約定的 CLAUDE.md；已經有的話，它會提出修改建議而不是覆蓋。然後再補上 Claude 自己發現不了的東西。

寫什麼

把它當作“不寫下來就得每次重複解釋”的地方。出現下面這些情況，就該往裡加一條：

• Claude 第二次犯同一個錯；
• 程式碼評審發現了它本該知道的專案慣例；
• 你在對話裡打了和上次一樣的糾正；
• 新同事也需要知道同樣的背景才能上手。

只寫每次工作階段都該知道的事實。多步驟的操作流程寫成 skill，需要時才載入；只對某一部分程式碼有效的規則，放進 .claude/rules。

怎麼寫才有效

寫能檢驗的具體規則，不寫籠統的要求：

• 短。每個 CLAUDE.md 控制在 200 行以內。越長越占上下文，遵守得也越差。
• 有結構。相關的規則放在同一個標題下，用清單，不寫大段文字。
• 不自相矛盾。兩條規則衝突時，Claude 可能隨便挑一條。定期清理過時的內容；Claude Code v2.1.283 起可以執行 /doctor prompt-audit，讓它找出過時、衝突或引用了不存在檔案的條目。
• 給人看的備註用 HTML 註釋。CLAUDE.md 裡的 <!-- 備註 --> 在送進上下文前會被去掉，不佔 token。

一個簡短的示例：

# 專案說明

## 命令
- 安裝依賴：pnpm install（不要用 npm）
- 執行測試：pnpm test，提交前必須透過
- 本地啟動：pnpm dev，埠 3000

## 約定
- TypeScript 嚴格模式，不用 any
- API 處理函式放在 src/api/handlers/，每個檔案一個路由
- 資料庫變更只透過 prisma migrate，不手改表結構

## 回覆
- 用中文回覆，程式碼註釋用英文

匯入其他檔案

用 @路徑 把別的檔案匯入進來，比如 詳見 @README 和 @docs/git-instructions.md。相對路徑以 CLAUDE.md 所在位置為準，匯入可以巢狀，最多四層。寫在反引號裡的 `@README` 不會被匯入。

匯入只是讓檔案更好組織，不會減少上下文開銷：被匯入的內容同樣每次都會載入。第一次遇到匯入專案目錄以外的檔案時，Claude Code 會彈出視窗請你確認。

用 .claude/rules 按範圍拆分

專案大了，可以在 .claude/rules/ 下按主題拆成多個 .md 檔案，比如 testing.md、api-design.md。沒有 paths 的規則和 CLAUDE.md 一樣在啟動時載入；加上 paths 的只在 Claude 處理匹配的檔案時才載入：

---
paths:
  - "src/api/**/*.ts"
---
# API 規則
- 所有介面都要做輸入校驗
- 錯誤統一用 ApiError 返回

CLAUDE.md 裡某一段已經長成多步流程的，可以改寫成 skill，用到時才載入，見 Skills 使用教程。

已經有 AGENTS.md 怎麼辦

Claude Code v2.1.277 起可以直接讀 AGENTS.md：專案裡沒有 CLAUDE.md 時，它讀 AGENTS.md；有 CLAUDE.md 時只讀 CLAUDE.md。想讓幾個程式設計工具共用一份說明，在 CLAUDE.md 裡寫一行 @AGENTS.md 匯入即可。

和花費、快取的關係

• 每一輪都會發。CLAUDE.md、自動記憶和不帶 paths 的規則，每一輪請求都隨上下文傳送。命中快取時只按快取讀取計費，但內容越長，沒命中時重寫的代價越大。這是要它短的另一個原因。
• 中途修改不會馬上生效。工作階段進行中改了 CLAUDE.md，這次工作階段看不到新內容，要等 /clear、/compact 或重啟（見 Anthropic 的 Claude Code 快取說明）。好處是改它不會讓當前工作階段的快取失效。

更多省錢做法見 省錢指南。

怎麼確認它被讀到了

• 在工作階段裡執行 /context，看 Memory files 下面列出的檔案。不在清單裡的，Claude 就看不到。
• 執行 /memory 可以列出、開啟和編輯各級 CLAUDE.md，也能開關自動記憶。

常見問題