---
title: "03 · 怎麼記住你的習慣"
description: "上下文是一次性的，關機就清空。Claude Code 怎麼跨會話記住你的專案、習慣、偏好？答案是雙軌記憶——你寫的 CLAUDE.md 持久指令 + 它自己寫的 Auto Memory 工作筆記。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

上一篇我們聊了上下文——一張很大但會清空的桌子。Aaron當時的第一個念頭是：那每次啟動 Claude Code，它豈不是什麼都不記得？翻文件發現 Anthropic 給的方案比想象中精妙——**兩套記憶並行**，一套你寫、一套它寫，把每天都是第一天這個問題徹底解決了。——Aaron

> [!NOTE]
> **這一篇用 13 分鐘換什麼**：上一篇 [02](/zh-Hant/docs/claude-code/understanding/02-context-window) 拆了上下文視窗——會話級、會清空。這一篇拆**跨會話**的記憶系統：你寫給 Claude 的專案指令（CLAUDE.md）+ Claude 自己積累的工作筆記（Auto Memory）。理解了雙軌設計，你才能判斷什麼資訊該寫哪、寫多少、放哪一層。

## 1. 一個新員工的麻煩

假設你僱了一個超級聰明的助手。什麼都會，反應飛快，解決問題一流。

但他每天早上來上班，**不記得昨天發生過什麼**。

你得重新告訴他：專案用的是 Next.js，資料庫是 PostgreSQL，程式碼風格遵循這套規範，構建命令是 `pnpm build`，部署走 Vercel，CI 在 GitHub Actions 裡……

第一天你覺得還行。第二天開始煩了。第三天你想辭退他。

這就是上一篇結尾提到的問題：上下文視窗是一次性的，會話結束就清空。如果 Claude Code 只有上下文，**每次啟動它對你的專案一無所知**——你得反覆解釋技術堆疊、構建命令、程式碼規範、架構決策……這些解釋本身還要佔上下文空間，擠掉了本來可以用來做正事的位置。

**換個設定**：同樣這個助手，但桌上放著一本你寫好的手冊——《新員工必讀》。每天來上班先翻一遍，五分鐘後進入狀態。**你再也不需要重複解釋任何事**。

這本手冊就是 Claude Code 的 **CLAUDE.md**。

## 2. 一份手冊，先解決最痛的問題

CLAUDE.md 是一個普通的 Markdown 檔案，任何文本編輯器都能開啟。

每次 Claude Code 啟動，它做的第一件事就是讀這個檔案。讀完之後，檔案內容變成這次會話的背景資訊——Claude 回答你的每個問題時，都**知道**手冊裡寫的東西。

那應該寫什麼？想象你給一個聰明但對你的專案一無所知的新同事寫一份備忘錄。你不會寫公司全部歷史，不會貼 500 行原始碼，不會把所有制度從頭抄一遍。你只會寫他**上班第一天最需要知道的那些事**。

具體三類：

- **這是什麼（WHAT）**：專案一句話介紹、技術堆疊、核心目錄結構
- **為什麼這樣設計（WHY）**：關鍵架構決策（如選 Next.js 因為需要 SSR）—— 這類資訊 Claude 從程式碼裡看不出來，必須你告訴它
- **怎麼操作（HOW）**：構建命令、測試命令、部署流程

> [!WARNING]
> **200 行預算**：官方建議 CLAUDE.md 控制在 **200 行以內**。檔案越長，消耗的上下文越多，Claude 對指令的遵循度也會下降。內容多時用 `@import` 引用外部檔案，或拆到 `.claude/rules/` 子目錄（按檔案路徑 glob 載入）。

## 3. 一份手冊不夠：4 層 scope

如果記憶只有一個 CLAUDE.md，你很快會碰到一個具體的麻煩：**個人偏好和專案規範混在一起**。

你喜歡中文回覆——這是個人偏好，跟專案無關。
專案用 TypeScript——這是專案規範，跟你個人無關。

在多個專案之間切換時，個人偏好每個專案都要寫一遍？團隊多個人時，每人偏好都要寫進專案 CLAUDE.md？

顯然得**分層**。Anthropic 的方案是 **4 層 scope**，按位置自動判斷屬於哪一層：

```files
📦 4 层 scope/
  ① Managed policy（系统级，最高优先）/
    macOS · /Library/Application Support/ClaudeCode/CLAUDE.md
    Linux · /etc/claude-code/CLAUDE.md
    Windows · C:\Program Files\ClaudeCode\CLAUDE.md
  ② Project（项目级，团队共享）/
    ./CLAUDE.md（项目根，提交 git）
    ./.claude/CLAUDE.md（同上，子目录形式）
  ③ User（用户级，跨所有项目）/
    ~/.claude/CLAUDE.md
  ④ Local（本地级，个人项目偏好）/
    ./CLAUDE.local.md（必须 .gitignore）
```

每一層各管各的，按官方載入順序拼起來：

```mermaid
sequenceDiagram
    participant CWD as 你的工作目錄
    participant Claude as Claude Code 啟動
    participant Ctx as 上下文視窗

    Claude->>CWD: 從專案根往上一路走
    CWD-->>Claude: 找到所有 CLAUDE.md / CLAUDE.local.md
    Claude->>Ctx: ① Managed policy（系統級）注入
    Claude->>Ctx: ② Project（專案根 ./CLAUDE.md）注入
    Claude->>Ctx: ③ User（~/.claude/CLAUDE.md）注入
    Claude->>Ctx: ④ Local（./CLAUDE.local.md）注入
    Note over Ctx: 離工作目錄越近的越晚注入<br/>越容易影響最終行為
    Claude->>Ctx: 也載入 MEMORY.md 前 200 行
    Note over Ctx: Auto Memory 索引（詳見 §5）
```

**載入機制底層**：Claude Code 從工作目錄**往上**逐層查詢 CLAUDE.md，**全部拼接**注入上下文（不是覆蓋）。同目錄下 CLAUDE.local.md 接在 CLAUDE.md 之後。子目錄的 CLAUDE.md 只在 Claude 實際讀取那個目錄下的檔案時**按需載入**。詳見[官方載入順序文件](https://code.claude.com/docs/en/memory#how-claude-md-files-load)。

日常使用中，**你只需要關注兩個檔案**：

- `~/.claude/CLAUDE.md` —— 你的個人偏好（跨專案）
- `專案根/CLAUDE.md` —— 專案規範（團隊共享，進 git）

**為什麼是"全部拼接"而不是"覆蓋"**：覆蓋會讓最深一層的 CLAUDE.md 幹掉所有上層規則——團隊規範被個人偏好覆蓋、個人偏好被本地實驗覆蓋，工程上不可控。拼接的代價是**所有層加起來不能太長**——如果 4 層都寫滿 200 行，啟動注入 800 行，主對話桌子被規則檔案佔掉一大半。這就是為什麼"剋制"是 CLAUDE.md 的核心寫作原則。

**新手最常見的寫法誤區**：把專案結構（目錄樹 / 檔案列表）、依賴列表（package.json 內容）、Git 歷史 / Commit 說明都抄進 CLAUDE.md。這些資訊**程式碼裡有**，每次會話再注入一遍 = 浪費 token。Claude 需要時直接讀就行——它在你電腦上（[01 篇](/zh-Hant/docs/claude-code/understanding/01-what-is-claude-code) 拆過）。

到這裡手冊系統已經很完整了。但還有一類資訊，手冊裝不下。

## 4. AI 還得自己記筆記

CLAUDE.md 解決了一個問題：**你把規則寫下來，Claude 每次啟動都看得見**。

但工作中還有一些東西不太適合寫進正式手冊。

比如你糾正了 Claude 一次：測試不要 mock 資料庫，用真實資料庫。這條資訊很有價值——下次寫測試時應該記住。但它不是專案規範，不太適合寫進 CLAUDE.md（團隊 review 時也奇怪）。

再比如 Claude 在幫你除錯時發現，某類錯誤的根因總是快取沒清。這是經驗教訓，對未來有用，但你不會主動寫進手冊。

這就是 **Auto Memory** 的角色。

**通俗講**：CLAUDE.md 是你寫的**員工手冊**，Auto Memory 是員工自己帶的**工作筆記本**。手冊寫公司規章，筆記本記工作中積累的經驗教訓。**你不需要告訴它什麼時候該記——它自己判斷**。

Auto Memory 是 Claude Code 自己維護的專案筆記系統（v2.1.59+ 預設開啟）。你什麼都不用做——Claude 在對話中**自動識別**哪些資訊值得記住，分類存到持久檔案裡。下次啟動新會話時，這些筆記自動可用。

存放位置：

```files
~/.claude/projects/<项目标识>/memory//
  MEMORY.md（索引，启动加载前 200 行 / 25KB）
  debugging.md（按需加载）
  patterns.md（按需加载）
  ...（其它主题文件）
```

`<專案標識>` 由 Claude Code 根據 git 儲存庫自動推導——同一個儲存庫的不同 worktree、子目錄共享同一份 Auto Memory。Auto Memory **機器本地**（不跨機同步）。

> [!WARNING]
> **200 行 / 25KB 載入上限**：啟動時只載入 `MEMORY.md` 的前 **200 行或 25KB**（取較小）。超過部分不進入會話起點，但 Claude 在工作中可以**按需讀取** topic 檔案（`debugging.md` 等）。這是為了避免筆記把工作臺從一開始就鋪滿。

## 5. 怎麼判斷什麼放哪？

現在兩套系統都清楚了。判斷標準很簡單——這條資訊是**規則**還是**經驗**？還是**Claude 直接看程式碼就能知道**？

<details>
<summary>📜 規則 → CLAUDE.md</summary>

**特徵**：必須遵守的、每次都需要的、應該共享給團隊的。

**典型內容**：

- 技術堆疊宣告（用 TypeScript / Next.js / PostgreSQL）
- 構建測試命令（`pnpm build` / `pnpm test`）
- 程式碼規範（縮排 / 命名 / 檔案組織）
- 架構約定（API 在 `src/api/handlers/` 下）
- 業務領域規則（訂單狀態機 / 許可權邊界）

**寫進哪一層**：

- 團隊共享 → `專案根/CLAUDE.md`（提交 git）
- 個人跨專案偏好 → `~/.claude/CLAUDE.md`
- 個人專案偏好 → `./CLAUDE.local.md`（加 `.gitignore`）

**什麼時候開始寫**：

- Claude 第二次犯同一個錯誤
- 程式碼 review 指出 Claude 本應知道的專案規則
- 你反覆在對話裡解釋同一個流程
- 新團隊成員需要同樣的上下文才能上手

</details>

<details>
<summary>💡 經驗 → Auto Memory</summary>

**特徵**：有用但非強制的、在工作中自然積累的、個人化或機器本地的。

**典型內容**：

- 你的糾正反饋（不要 mock 資料庫 / 用 pnpm 不要 npm）
- 除錯中發現的規律（這類報錯根因總是快取沒清）
- 專案臨時狀態（這周凍結主分支 / X 服務停機維護）
- 某個檔案 / 函式的非顯然約定（看起來像 X 但實際是 Y）
- 偶發但重要的環境差異（CI 跟本地行為不同）

**怎麼寫**：

- 你不用主動寫——Claude 自己判斷寫什麼
- 想主動新增：直接告訴 Claude 比如**以後都用 pnpm 不要 npm**，它會自動寫進 Auto Memory
- 想編輯：用 `/memory` 命令開啟

**怎麼查**：

- `/memory` 列出所有當前會話載入的指令檔案
- 直接開啟 `~/.claude/projects/<專案>/memory/` 看 markdown

</details>

<details>
<summary>🔍 程式碼裡有 → 不存</summary>

**特徵**：Claude 隨時能從專案程式碼 / 檔案 / Git 歷史讀到的事實。

**典型內容**：

- 檔案結構 / 目錄組織（`ls` 就能看）
- 函式簽名 / 類定義（`grep` 就能看）
- 歷史變更 / 誰改了什麼（`git log` 就能看）
- package.json 的依賴列表（直接 `cat` 就行）
- README 已經寫過的內容

**為什麼不存**：

- 重複存 = 浪費上下文 token + 容易跟程式碼不同步
- Claude 需要時直接讀就行——它在你電腦上（[01 篇拆過](/zh-Hant/docs/claude-code/understanding/01-what-is-claude-code)）
- 資訊源唯一才不會自相矛盾

**反模式**：把 README 內容複製進 CLAUDE.md / 把目錄結構 ASCII 樹寫進 CLAUDE.md / 把測試用例列表寫進 CLAUDE.md。

</details>

> [!TIP]
> **速記**：**每次都需要 → CLAUDE.md**。**工作中發現的 → Auto Memory**。**程式碼裡有的 → 不存**。

**3 個判斷練習** —— 下面三句話分別該放哪裡？讀完答案再看你判斷對了幾個：

> **場景 A**：專案用 Next.js 14 + TypeScript + Prisma，所有 API 必須返回 `{ data, error }` 格式。
>
> **場景 B**：你昨天發現 Claude 總是把測試 mock 資料庫——你糾正後說"以後所有測試都連真實測試庫"。
>
> **場景 C**：專案原始碼結構（`src/app/` / `src/components/` / `src/api/handlers/` ...）。

<details>
<summary>📌 看答案</summary>

- **A → 專案根 `CLAUDE.md`**：是專案級長期規範，每個團隊成員都需要，進 git 共享。
- **B → Auto Memory**（自動記憶）：是工作中積累的糾正反饋，不需要正式寫進專案規範，Claude 自己會記到 `~/.claude/projects/<專案>/memory/`。
- **C → 不存**：原始碼結構 `ls` 就能看到，寫進 CLAUDE.md = 浪費 token + 跟程式碼不同步（重構後 CLAUDE.md 容易忘改）。

判斷訣竅——問自己：
1. 這條資訊**每次會話**都要進上下文嗎？是 → CLAUDE.md。
2. 這條資訊是**工作中臨時發現的糾正**？是 → Auto Memory（讓 Claude 自己記）。
3. 這條資訊**程式碼裡 / `ls` / `git log` 能直接讀到**？是 → 不存。

</details>

## 6. 完整的畫面

把前面所有內容串起來，Claude Code 啟動時的資訊架構是這樣的：

| 時機 | 自動載入 | 來源 |
|------|---------|------|
| **會話開始** | 系統提示（內建） | Claude Code 自己 |
| **會話開始** | CLAUDE.md（4 層全量拼接） | 你寫的 |
| **會話開始** | MEMORY.md 前 200 行 / 25KB | Claude 自己寫的 |
| **工作進行中** | 你和 Claude 的對話、讀取的檔案、命令輸出 | 即時累積進上下文視窗 |
| **工作進行中** | Claude 自動寫 Auto Memory（識別值得記的資訊）| Claude 決策 |
| **工作進行中** | 子目錄 CLAUDE.md / `.claude/rules/*.md` 按 glob 命中 | 按需載入 |
| **會話結束** | 上下文清空 | —— |
| **下次啟動** | CLAUDE.md + MEMORY.md 還在 | 跨會話保留 |

> [!NOTE]
> **底層邏輯**：兩套記憶系統的設計**對應了兩種資訊天然屬性**——**每次對話都需要知道的**（CLAUDE.md）和**在工作中自然積累的**（Auto Memory）。把所有資訊都塞進 CLAUDE.md 等於檔案膨脹 + 團隊 review 噪音；讓 AI 自己積累而不留人寫規則的口子，團隊會失去顯式約定。**兩套必須並存**。

## 7. 排障：Claude 不聽 CLAUDE.md 怎麼辦

CLAUDE.md 是**上下文**不是**強制配置**。Claude 會讀它、嘗試遵守，但**不保證嚴格服從**——尤其是模糊或衝突的指令。

<details>
<summary>排障 1 · 用 /memory 檢查到底載入了哪些檔案</summary>

`/memory` 命令列出當前會話所有已載入的 CLAUDE.md / CLAUDE.local.md / `.claude/rules/*.md`。

如果你的指令檔案**沒出現在列表裡** → Claude 根本沒看到。

常見原因：
- 檔案不在工作目錄的祖先鏈上
- 子目錄 CLAUDE.md（只在 Claude 讀子目錄檔案時按需載入）
- 用了 `--add-dir` 但沒設 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`

</details>

<details>
<summary>排障 2 · 讓指令更具體</summary>

`格式化程式碼` ❌ → `用 2 空格縮排` ✅
`測試改動` ❌ → `提交前跑 pnpm test` ✅
`保持檔案組織` ❌ → `API 處理器在 src/api/handlers/` ✅

模糊的話 Claude 會自由發揮，**具體到能驗證的程度**才能穩定遵循。

</details>

<details>
<summary>排障 3 · 檔案超過 200 行</summary>

檔案越長，消耗上下文越多，對指令的遵循度反而下降。

**解法**：

- **路徑範圍規則** → 拆到 `.claude/rules/` 加 `paths: [...]` frontmatter，只在 Claude 處理匹配檔案時載入
- **拆分多檔案** → 用 `@path/to/sub.md` import（注意：import 的內容仍然占上下文 token，只是組織上分開）
- **剔除可推斷的內容** → 檔案結構 / 函式簽名等程式碼裡有的，刪掉

</details>

<details>
<summary>排障 4 · 多個 CLAUDE.md 互相沖突</summary>

monorepo / 大型專案裡，祖先目錄的 CLAUDE.md 可能跟當前專案的指令矛盾。Claude 會**任意挑一個**，行為不穩定。

**解法**：

- 用 `/memory` 看所有載入的檔案
- 找到衝突指令，統一表述
- 不需要的祖先檔案用 `claudeMdExcludes` 設定排除

</details>

<details>
<summary>排障 5 · /compact 後指令好像沒了</summary>

專案根 CLAUDE.md **會** 在 `/compact` 後被重新注入。
子目錄 CLAUDE.md **不會**自動重新注入，下次 Claude 讀子目錄檔案時才會重新載入。

如果 `/compact` 後指令丟了 → 大機率是你**只在對話裡口頭給過**的指令，沒寫進檔案。**寫進 CLAUDE.md 才能跨 compact 持久**。

</details>

## 8. 檢驗你真懂了嗎

費曼說，檢驗你是不是真的理解一件事，試試能不能解釋給朋友聽。

| # | 試著用自己的話回答 | 對應章節 |
|:-:|------|------|
| 1 | 有人說 Claude Code 記憶力很好什麼都能記住——你能解釋為什麼這說法不準確？它有幾種記憶，各自的特點？ | §1 + §6 |
| 2 | CLAUDE.md 為什麼建議控制在 200 行以內？背後的原理是什麼？超過會怎樣？ | §2 + 排障 3 |
| 3 | **動手題** ⭐：開啟你當前專案的 `CLAUDE.md`（如果沒有，新建一個）。**刪掉**所有"`ls` / `git log` / `cat package.json` 能查到的內容"——目錄結構、依賴列表、Git 歷史描述等。剩下的就是真正"每次會話都要進上下文"的專案規範。如果剩不到 50 行，證明你以前在 CLAUDE.md 裡塞了太多 Claude 自己能查的事實。| §5 |

> [!TIP]
> **過關標準**：能用一句話說清——**Claude Code 的跨會話記憶是雙軌的：你寫的 CLAUDE.md（4 層 scope，規則）+ 它寫的 Auto Memory（專案本地，經驗）；程式碼裡有的事實不重複存。**

<details id="glossary">
<summary>📖 本篇術語速查表</summary>

| 英文 / 縮寫 | 中文 | 一句話解釋 |
|-------------|------|-----------|
| CLAUDE.md | 專案記憶檔案 | 你寫的持久指令，每次啟動自動讀，Markdown 格式 |
| `~/.claude/CLAUDE.md` | 使用者級記憶 | 跨所有專案的個人偏好 |
| `./CLAUDE.local.md` | 本地級記憶 | 當前專案的個人偏好（必須加 `.gitignore`）|
| Managed policy | 系統級策略 | IT/DevOps 部署的全公司強制指令 |
| `.claude/rules/` | 規則目錄 | 大專案下按主題拆分的指令檔案，支援 `paths:` glob 過濾 |
| `@path/to/file` | import 語法 | CLAUDE.md 引用其它檔案，遞迴最多 5 層 |
| Auto Memory | 自動記憶 | Claude 自己維護的專案本地筆記系統（v2.1.59+ 預設開啟）|
| MEMORY.md | 自動記憶主檔案 | Auto Memory 索引，啟動載入前 200 行 / 25KB |
| `/memory` | 記憶檢視命令 | 列出當前會話已載入的所有指令檔案 |
| `claudeMdExcludes` | 排除設定 | settings 裡指定不載入某些 CLAUDE.md（monorepo 場景）|
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 環境變數 | 設為 `1` 關閉 Auto Memory |

</details>

## 官方資料

- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory)

## 接下來去哪

<Cards>
  <Card title="➡️ 04 · 怎麼和 AI 說話" href="/zh-Hant/docs/claude-code/understanding/04-prompting">
    有了記憶，還得會說話。提示詞不是模板遊戲，是資訊密度遊戲——目標 / 上下文 / 邊界 / 驗收 4 件套。
  </Card>
  <Card title="06 · 把重複的話寫成檔案（可跳讀）" href="/zh-Hant/docs/claude-code/understanding/06-command-files">
    規則之外還有工作流。Skills 是把多步流程沉澱成可複用單元——記憶系統的進化形態。
  </Card>
  <Card title="02 · 一次能看多少程式碼（上一篇）" href="/zh-Hant/docs/claude-code/understanding/02-context-window">
    複習一下：上下文是會話級的工作臺。本篇的雙軌記憶就是為了解決**每次對話都需要知道的**那部分。
  </Card>
</Cards>

不用按順序全讀。挑你最好奇的那條線走就行。
