CLAUDE.md要寫什麼？專案規則範例、匯入與自動記憶

CLAUDE.md 是 Claude Code 每次開會話都會讀的說明檔，寫的是每次都要知道的指令與規則。自動記憶（auto memory）則是 Claude 自己寫的筆記，記下你的偏好與糾正。兩者都只是給 Claude 的上下文，不是強制設定；一定要擋下的動作，要改用 hook 或權限規則。

這篇講 CLAUDE.md 放在哪裡、怎麼載入、該寫什麼，以及 @ 匯入、依路徑載入的規則檔與自動記憶怎麼運作。還沒裝好 Claude Code 的話，先看Claude Code 是什麼？；功能規格以官方文件〈How Claude remembers your project〉為準。

下面的例子都用同一個專案：假設你在做一個記帳網站，叫做豪享記帳。前端用 Next.js 寫在 web/，後端用 Go 寫在 api/。

CLAUDE.md 和自動記憶差在哪？

兩者都會在每次對話開頭載入，差別在誰寫、寫什麼。CLAUDE.md 由你寫，放規則與指令；自動記憶由 Claude 寫，放它從工作中學到的事。

CLAUDE.md 與自動記憶的差別

資料來源：Claude Code 官方文件〈How Claude remembers your project〉

Claude 會盡量照兩者做，但不保證嚴格遵守。官方文件說明，CLAUDE.md 的內容放在系統提示之後，以使用者訊息的形式送進去。所以寫得越具體、越精簡，Claude 照做得越穩定。

CLAUDE.md 要放在哪裡？四個層級與載入順序

CLAUDE.md 有四個層級，範圍由大到小，載入也照這個順序。內容會串接在一起，不會互相覆蓋。

CLAUDE.md 的四個層級

資料來源：Claude Code 官方文件〈How Claude remembers your project〉

CLAUDE.md 由大到小依序載入，內容串接、不覆蓋

載入時有四個細節要知道：

• 往上逐層讀：Claude Code 會讀工作目錄與上層各目錄的 CLAUDE.md 和 CLAUDE.local.md。
• 越近越晚讀：內容從檔案系統根目錄往下排到工作目錄，離工作目錄越近的越晚讀。
• 子目錄需要時才載入：子目錄的 CLAUDE.md 不在啟動時讀，等 Claude 讀寫那個目錄裡的檔案才載入。
• HTML 註解不佔上下文：區塊層級的 HTML 註解在送進 Claude 之前會被拿掉，適合留給維護的人看。

以豪享記帳為例，專案的檔案可以這樣放：

hao-ledger/
├── CLAUDE.md            # 團隊共用：指令、慣例、注意事項
├── CLAUDE.local.md      # 只給自己，加進 .gitignore
├── .claude/
│   └── rules/
│       ├── frontend.md  # 改 web/ 的檔案時才載入
│       └── backend.md   # 改 api/ 的檔案時才載入
├── web/                 # Next.js 前端
└── api/                 # Go 後端

放好之後，在會話裡執行 /context，看 Memory files 清單裡有沒有這些檔案。執行 /memory 會列出各層級的檔案位置，選一個就能用編輯器打開。

CLAUDE.md 該寫什麼？

官方的建議是：把你原本會再講一次的事寫下來。出現下面這些情況，就是該補 CLAUDE.md 的時候：

• Claude 第二次犯同樣的錯。
• code review 抓到 Claude 本來應該知道的專案慣例。
• 上次會話打過的糾正，這次又打了一次。
• 新同事加入，也需要同樣的背景才能上手。

寫法上有四個原則：

• 寫到可以驗證：「縮排用 2 格」比「程式碼要整齊」好；「提交前跑 make lint」比「記得測試」好。
• 每份 200 行內：檔案越長，佔的上下文越多，Claude 照做的程度也會下降。
• 用標題和條列分組：相關的規則放在同一個標題底下，比一大段文字好讀。
• 不要互相矛盾：兩條規則衝突時，Claude 可能任選一條。

豪享記帳的 CLAUDE.md 範例

下面是豪享記帳根目錄的 CLAUDE.md。重點放在 Claude 從程式碼看不出來的事，例如金額怎麼存、哪個資料夾不要動。

# 豪享記帳

前端在 `web/`（Next.js），後端在 `api/`（Go），資料庫用 PostgreSQL。

## 常用指令
- 前端開發：`cd web && npm run dev`
- 前端測試：`cd web && npm test`
- 後端測試：`cd api && go test ./...`
- 提交前先跑 `make lint`

## 程式慣例
- 金額一律存成整數「分」，不用浮點數
- API 錯誤格式固定為 `{"error": {"code": "...", "message": "..."}}`
- 新的 API handler 放在 `api/internal/handler/`

## 注意事項
- 改資料表要新增 migration 檔，不改已經上線的 migration
- `api/internal/legacy/` 是舊版匯入程式，沒有我同意不要改

<!-- 維護備註：2026-10 起金額改存整數分，舊資料已轉換完成 -->

最後一行是 HTML 註解，給維護的人看，不會送進 Claude。也可以先執行 /init，讓 Claude 分析程式碼、產生起始的 CLAUDE.md。之後再補上它自己看不出來的規則。

哪些內容不該寫在 CLAUDE.md？

CLAUDE.md 每次會話都會整份載入，所以只放每次都用得到的事。下面這幾類放到別的地方更合適：

內容該放哪裡

資料來源：Claude Code 官方文件的功能總覽與記憶頁

@ 匯入怎麼用？

CLAUDE.md 可以用 @路徑 匯入其他檔案，被匯入的檔案會在啟動時一起展開。相對路徑以寫匯入的那個檔案為準，不是以工作目錄為準。被匯入的檔案還可以再匯入，最多 4 層。

專案說明見 @README.md，前端可用的指令見 @web/package.json。

## 其他規範
- Git 流程：@docs/git-workflow.md
- 個人偏好：@~/.claude/hao-ledger-personal.md

用匯入之前，先知道四件事：

• 不會省上下文：匯入只是把長檔案拆開整理，被匯入的檔案啟動時一樣全部載入。
• 路徑有空格要加反斜線：例如 @Design\ Docs/api.md；用引號包起來的路徑不會匯入。
• 只想提到、不想匯入：把路徑包成行內程式碼（用反引號包起來），就只是一般文字。
• 工作目錄外的檔案要核准：專案檔第一次匯入工作目錄外的檔案，Claude Code 會跳出核准視窗；拒絕之後就不會再匯入。

加進 .gitignore 的 CLAUDE.local.md，只存在你建立它的那個 worktree。想在多個 worktree 共用個人偏好，就像上面最後一行那樣，從家目錄匯入一個檔案。

規則太多怎麼拆？用 .claude/rules/ 依路徑載入

專案變大之後，可以把規則拆成 .claude/rules/ 底下的多個 Markdown 檔，一個檔案講一個主題。沒有寫 paths 的規則檔，啟動時就載入。寫了 paths 的規則檔，要等 Claude 讀取、寫入或編輯符合的檔案時才載入。

---
paths:
  - "web/**/*.{ts,tsx}"
---

# 前端規則

- 元件放在 `web/components/`，一個檔案一個元件
- 金額顯示一律用 `formatTWD()`，不自己組字串
- 資料讀取用 `web/lib/api.ts` 的函式，不在元件裡直接 fetch

paths 用 glob 寫法，可以列多個樣式，也可以用大括號一次對多個副檔名。規則檔的 frontmatter 只會讀 paths，其他欄位會被忽略。想套用到所有專案的個人規則，放在 ~/.claude/rules/。

子目錄放一份 CLAUDE.md 也有類似效果。同一類規則選一種放法就好，比較不會兩邊寫得不一樣。

自動記憶是什麼？四種記憶與 MEMORY.md 索引

自動記憶是 Claude 邊工作邊替自己記的筆記，在本機會話預設開啟。它不是每次都會記，只有判斷以後用得到的事才會存下來。

自動記憶的四種類型（以豪享記帳為例）

資料來源：Claude Code 官方文件〈How Claude remembers your project〉

能從程式碼推出來的東西，例如架構、檔案路徑、除錯的修法，Claude 不會記。CLAUDE.md 已經寫過的，它也不會再記一次。

自動記憶存在哪裡？

每個專案的記憶放在 ~/.claude/projects/<project>/memory/。<project> 由 git repo 決定，同一個 repo 的 worktree 與子目錄共用一份；不在 git repo 裡，就用專案根目錄。記憶只存在這台電腦，不會跨電腦或雲端同步。

~/.claude/projects/<project>/memory/
├── MEMORY.md                # 索引，一筆一行，每次會話載入
├── user_role.md             # 一則記憶
├── feedback_test_db.md      # 一則記憶
└── project_receipt_ocr.md   # 一則記憶

MEMORY.md 是索引，啟動時載入前 200 行或前 25KB，先到的那個為準，超過的部分不會載入。主題檔啟動時不讀，Claude 需要時才用讀檔工具打開。

自動記憶的結構：索引常駐，主題檔需要時才讀

豪享記帳的 MEMORY.md 可能長這樣，每一行只寫一句話。

MEMORY.md 範例

- [後端測試不 mock 資料庫](feedback_test_db.md) — 連測試資料庫跑，mock 曾漏掉欄位錯誤
- [收據拍照記帳時程](project_receipt_ocr.md) — 11 月底前上線，先做手機版
- [錯誤追蹤在哪](reference_error_tracker.md) — 正式站錯誤看錯誤追蹤後台
- [使用者背景](user_role.md) — 後端工程師，React 要多解釋

主題檔範例：feedback_test_db.md

---
name: 後端測試不 mock 資料庫
description: 豪享記帳的 Go 測試一律連測試資料庫，不用 mock
type: feedback
---

後端測試一律連 Docker 起的 PostgreSQL 測試資料庫，不要 mock。

**Why：** 上個月 mock 的測試全部通過，正式站卻因為 migration 少一個欄位壞掉。

**How to apply：** 寫或改 `api/` 的測試時，用 `testutil.NewDB()` 開測試資料庫；假資料放 `api/testdata/`。

官方文件寫明的欄位是 frontmatter 的 type，值是上面四類之一；name 與 description 是方便自己管理的慣例。

name、description 與 Why、How to apply 的段落，是記憶檔常見的寫法，不是文件規定的格式。寫明原因的好處是：遇到規則沒寫到的情況，Claude 比較能自己判斷。

索引寫太長會怎樣？

我對照官方文件檢查自己的記憶，發現有一份 MEMORY.md 已經約 29KB、131 行。行數離 200 還很遠，但超過 25KB 之後的最後十幾筆，開新會話時不會載入。原因是每一行都寫了日期、數字和進度，平均一行約 230 個位元組。

注意：中文在 UTF-8 通常一個字佔 3 個位元組，寫中文的索引會先碰到 25KB，而不是 200 行。

官方的建議是索引一筆一行，細節搬進主題檔，過時的合併或刪掉。索引超過 200 行或 25KB 的部分，啟動時不會載入，所以要定期整理。

自動記憶怎麼開關、怎麼檢查？

自動記憶的檔案都是一般的 Markdown，可以隨時打開來改或刪。常用的操作有這幾個：

• 看記了什麼：執行 /memory，選自動記憶資料夾，就能瀏覽、編輯或刪除。
• 整個關掉：在 /memory 裡切換開關。設定會存進 ~/.claude/settings.json 的 autoMemoryEnabled。
• 只關一個專案：在該專案的 .claude/settings.json 寫入下面的設定。
• 用環境變數關閉：設定 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
• 換存放位置：設定 autoMemoryDirectory，值要是絕對路徑或 ~/ 開頭。

{
  "autoMemoryEnabled": false
}

看到「Saved 2 memories」或「Recalled 2 memories」，代表 Claude 在讀寫記憶。想讓它記住某件事，直接說「記住：PR 說明要附測試指令」，它會存進自動記憶。想寫進 CLAUDE.md，就說「把這條加到 CLAUDE.md」，或用 /memory 自己打開來改。

回饋怎麼變成規則？

官方建議依觸發條件逐步加設定，不用一開始就全部設好。和這章有關的時機有三個：

• 同一個慣例或指令錯兩次：寫進 CLAUDE.md。
• 同一套多步驟流程貼到第三次：寫成 skill。
• 希望每次都自動發生、不用開口：寫成 hook。

回饋變成規則：先記下來，重複了就升級

我的做法是把每次的回饋寫成記憶，下次就不用再講一次。同一條回饋反覆用到、內容也穩定了，再搬進對應的規範檔，讓每次會話都照同一份做。

搬家之後，要把原本的記憶縮成一句或刪掉。兩邊各留一份完整內容，改了一邊、忘了另一邊，Claude 遇到矛盾時可能任選一條。

要檢查規則有沒有過時或互相矛盾，可以執行 /doctor prompt-audit。這個指令需要 v2.1.283 以上，會找出寫給舊模型的指示、提到不存在的檔案或指令的地方，以及互相衝突的內容。結果是一份附修改建議的報告，你同意之後才會改檔。

哪些規則不能只寫在 CLAUDE.md？

必須每次都成立的規則，不能只靠 CLAUDE.md。官方文件的說法是：CLAUDE.md 寫「不要改 .env」只是請求，不是保證；用 PreToolUse hook 擋下編輯，才是強制。

「不准讀 .env」這種針對工具的限制，也可以直接寫成權限規則：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

權限規則由 Claude Code 執行，不管 Claude 怎麼判斷都會生效。hook 與權限的完整寫法，留到 Hooks 與權限那一章說明。

舊寫法和新寫法差在哪？

我回頭對照官方文件檢查自己的設定，找到幾個可以改的地方。換成豪享記帳的情境如下：

舊寫法與新寫法對照

資料來源：Claude Code 官方文件的記憶與功能總覽頁

常見問題

Q1：CLAUDE.md 可以自動產生嗎？

可以。在專案裡執行 /init，Claude 會分析程式碼，產生一份含建置指令與專案慣例的 CLAUDE.md。已經有 CLAUDE.md 時，執行前先備份，再比對 /init 產生的內容。

Q2：專案已經有 AGENTS.md，還要寫 CLAUDE.md 嗎？

工作目錄和上層都沒有 CLAUDE.md 時，Claude Code 會直接讀 AGENTS.md。這需要 v2.1.277 以上的版本。兩種都想用，就在 CLAUDE.md 第一行寫 @AGENTS.md，下面再補 Claude 專用的規則。

Q3：執行 /compact 之後，CLAUDE.md 的規則會不見嗎？

專案根目錄的 CLAUDE.md 不會，壓縮之後 Claude 會從磁碟重新讀一次。子目錄的 CLAUDE.md 和有 paths 的規則檔，會在需要時重新載入。只在對話裡講過的指示才會消失，要長期有效就寫進 CLAUDE.md。

Q4：子代理讀得到 CLAUDE.md 和自動記憶嗎？

一般的子代理啟動時會載入 CLAUDE.md 與 git 狀態，內建的 Explore 與 Plan 則兩者都不載入。主對話的自動記憶不會傳給子代理，繼承整段對話的分支除外。子代理要有自己的記憶，要在它的設定加上 memory 欄位。

延伸閱讀

• Claude Code Skill怎麼建立？觸發描述與參考檔：把多步驟流程寫成 skill，需要時才載入
• Claude Code Hooks與權限怎麼設？擋指令與沙箱：一定要擋下的動作，改用 hook 與權限規則
• Claude Code子代理怎麼分工？角色設定、平行與驗收：子代理的設定檔、工具白名單與記憶欄位
• 一人開發怎麼用AI團隊？Claude Code分工與上版審查：我用 Claude Code 組 AI 團隊的實際做法