---
title: "06 - CLAUDE.md 與記憶系統"
type: note
specialty: Programming
tags: [claude-code-cli從0開始使用教學, 06-memory, claude-md, rules]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 06 - CLAUDE.md 與記憶系統

← [[05-權限模式與安全]] | [[00-Index]] | 下一篇 → [[07-Skills與斜線指令]]

---

## 兩套記憶系統

每個 session 都從空白的 context 開始。有兩個機制把知識帶過去：

| | **CLAUDE.md** | **Auto memory** |
|---|---|---|
| 誰寫的 | **你** | **Claude 自己** |
| 內容 | 指示與規則 | 學到的東西與模式 |
| 範圍 | 專案 / 使用者 / 組織 | 每個 repo 一份，worktree 共用 |
| 載入 | 每個 session 全部載入 | 每個 session（前 200 行或 25KB）|
| 用來放 | 程式規範、工作流程、專案架構 | build 指令、除錯心得、Claude 發現的偏好 |

> 🔴 **兩者都是「上下文」不是「強制設定」。** Claude 讀了會盡量遵守，但不保證。**要無論如何都擋下某個動作，用 `PreToolUse` hook。**

---

## CLAUDE.md 放哪裡

按載入順序（範圍由寬到窄，越後面越接近你、越晚被讀到）：

| 範圍 | 位置 | 用途 |
|---|---|---|
| **Managed policy** | macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`<br>Linux/WSL `/etc/claude-code/CLAUDE.md`<br>Windows `C:\Program Files\ClaudeCode\CLAUDE.md` | 組織層級，個人設定無法排除 |
| **User** | `~/.claude/CLAUDE.md` | 你所有專案的個人偏好 |
| **Project** | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 團隊共享，進版控 |
| **Local** | `./CLAUDE.local.md` | 個人的專案偏好，**要加進 `.gitignore`** |

### 載入規則（很重要）

- Claude Code 從**目前工作目錄往上走**，每一層檢查 `CLAUDE.md` 和 `CLAUDE.local.md`。
- 全部**串接**進 context，不是互相覆蓋。
- 順序是**從檔案系統根目錄往下到你的工作目錄**——所以離你啟動位置越近的越晚被讀到。
- 同一層裡 `CLAUDE.local.md` 接在 `CLAUDE.md` 後面。
- **子目錄裡的 CLAUDE.md 不會在啟動時載入**，而是在 Claude 讀到那個子目錄的檔案時才載入。

👉 **實務結論**：一定要 `cd` 到 repo 根目錄再開 `claude`，否則專案的 `CLAUDE.md` 讀不到。用 `/context` 確認 **Memory files** 裡有它。

---

## 怎麼寫才有效

官方三條原則：

**大小**：**每個 CLAUDE.md 目標 200 行以內**。太長吃 context 而且降低遵守率。

> ⚠️ 你的 `Obsidian-med-note/CLAUDE.md` 和 `Taiwan_IM_board/CLAUDE.md` 都遠超過 200 行。這是**刻意的取捨**（醫學安全規則不能省），但值得知道代價：越長，個別規則被遵守的機率越低。
> **可以考慮的優化**：把「只在特定情境用得到」的段落搬去 `.claude/rules/`（路徑限定）或 skill（用到才載入）。例如 vault 的 §8 語言學習筆記、§9 理財區，完全可以做成 path-scoped rules。

**結構**：用 markdown 標題和條列分組。

**具體**：寫得能驗證。
- ✅「用 2 空格縮排」 ❌「格式弄好」
- ✅「commit 前跑 `npm test`」 ❌「測試你的變更」

**一致**：兩條規則互相矛盾時，Claude 可能**任意挑一條**。定期檢查有沒有過時或衝突的指示。

---

## `/init` 產生起始檔

```
/init
```

Claude 分析 codebase，產出含 build 指令、測試方式、專案慣例的 `CLAUDE.md`。**已經有的話它會建議改進而不是覆蓋。**

`/init` 還會讀 Cursor rules（`.cursor/rules/`、`.cursorrules`）和 Copilot rules（`.github/copilot-instructions.md`）並整合。

設 `CLAUDE_CODE_NEW_INIT=1` 可以開互動式多階段流程：問你要設哪些東西（CLAUDE.md / skills / hooks）、用 subagent 探索、追問補缺、最後給你一份可審閱的提案才寫檔。

---

## 匯入其他檔案（`@` 語法）

```markdown
See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md
```

- 相對路徑是**相對於含這個 import 的檔案**，不是工作目錄。
- 可以遞迴匯入，最多 **4 層**。
- **想在 CLAUDE.md 裡提到路徑但不匯入 → 用反引號包起來**：`` `@README` `` 是純文字，`@README` 會匯入。
- 匯入的檔案**在啟動時一起載入 context**，所以拆檔案有助於組織但**不會省 context**。

> ⚠️ **外部匯入的警告**：專案層級 memory 檔裡，路徑解析到工作目錄外的匯入算「external」。第一次遇到時 Claude Code 會跳確認對話框列出那些檔案。這是在保護你不被別人 commit 進共享專案的東西影響。使用者層級（`~/.claude/`）的匯入是你自己寫的，不跳。

### AGENTS.md 怎麼辦？

**Claude Code 讀 `CLAUDE.md`，不讀 `AGENTS.md`。** 如果你的 repo 已經有 `AGENTS.md` 給別的 agent 用（例如 Codex），建一個 `CLAUDE.md` 匯入它：

```markdown
@AGENTS.md

## Claude Code

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

也可以用 symlink（`ln -s AGENTS.md CLAUDE.md`），但 Windows 建 symlink 要管理員權限或開發者模式，**建議用 `@AGENTS.md` 匯入**。

> 💡 你的 `Obsidian-med-note` 同時有 `AGENTS.md` 和 `CLAUDE.md`。如果兩份內容有重疊，考慮讓 `CLAUDE.md` 用 `@AGENTS.md` 匯入共通部分，只在下面加 Claude 專屬規則——**避免兩份漂移**。

---

## `.claude/rules/`（路徑限定規則）⭐

大專案可以把指示拆成多個檔案：

```text
your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md
```

**殺手功能是路徑限定**——用 YAML frontmatter 的 `paths`：

```markdown
---
paths:
  - "理財(FIN)/**/*.md"
---

# 理財筆記規則

- 專有名詞**中英並列**（與醫學筆記的「一律英文」相反）
- 財務數字絕不捏造，一律 web 查證權威來源並標查證日
- `transactions.csv` 是唯一真相，報酬率由 compute.py 算，不手填
- 不要在本地跑 compute.py（proxy 擋 Yahoo Finance）
```

這樣這段規則**只有在 Claude 碰理財資料夾的檔案時才進 context**，平常不佔位置。

Glob 語法：

| Pattern | 比對 |
|---|---|
| `**/*.ts` | 任何目錄下的所有 TypeScript 檔 |
| `src/**/*` | `src/` 底下所有檔案 |
| `*.md` | 專案根目錄的 markdown |
| `src/**/*.{ts,tsx}` | 大括號展開多副檔名 |

沒有 `paths` 的 rule 檔會**無條件在啟動時載入**，優先級跟 `.claude/CLAUDE.md` 一樣。

使用者層級規則放 `~/.claude/rules/`，**先於**專案 rules 載入（所以專案 rules 優先級較高）。

> 🔴 **這是你最該做的一個優化。** 把 vault 的 `CLAUDE.md` 從約 200 行的醫學核心規則 + 一堆情境規則，重構成：
> - `CLAUDE.md`：§0 三條鐵律、§1 語言硬規則、§3 wiki SOP、§5 git（**永遠要在 context 裡的**）
> - `.claude/rules/lang-notes.md`（`paths: 語言/**`）：§8
> - `.claude/rules/finance.md`（`paths: 理財(FIN)/**`）：§9
> - `.claude/rules/quartz.md`（`paths: **/*.md`）：§6 圖片與 YAML 規則
>
> 效果：主檔案變短 → 核心醫學規則的遵守率上升。

---

## Auto memory（Claude 自己記的）

Claude 邊工作邊幫自己記筆記：build 指令、除錯心得、架構筆記、程式風格偏好、工作習慣。它**不是每個 session 都存**，而是判斷「這件事以後用得到嗎」。

**預設是開的。** 關掉：`/memory` 裡有開關（寫進 `~/.claude/settings.json` 的 `autoMemoryEnabled`），或環境變數 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`。

**存在哪**：`~/.claude/projects/<project>/memory/`
- `<project>` 由 git repo 推導，所以**同一個 repo 的所有 worktree 和子目錄共用一份**
- 結構是一個 `MEMORY.md` 索引 + 若干主題檔（`debugging.md`、`api-conventions.md`…）
- **只有 `MEMORY.md` 的前 200 行 / 25KB 會在每個 session 開頭載入**；主題檔是 Claude 需要時才讀

**機器本機的**，不跨機器、不進雲端 session。

看和編輯：
```
/memory
```

> 💡 你說「以後 PMID 一律要查證」這種話時，Claude 會把它存進 auto memory。**要進 CLAUDE.md 的話要明講**：「把這條加到 CLAUDE.md」。

---

## 排查：「Claude 沒照我的 CLAUDE.md 做」

官方給的除錯步驟：

1. **跑 `/context`**，看 **Memory files** 清單裡有沒有你的檔案。**沒有 = Claude 根本看不到。**
2. 確認那份 CLAUDE.md 在會被載入的位置（見上面的載入規則）。
3. **把指示寫得更具體。**
4. **找互相矛盾的指示**——跨多份 CLAUDE.md 檢查。

如果那條指示是「必須在某個時間點執行」的（例如每次 commit 前、每次改檔後）→ **寫成 hook**，不要寫在 CLAUDE.md。

想在 system prompt 層級下指示 → `--append-system-prompt`（但每次呼叫都要帶，比較適合腳本）。

> 💡 進階除錯：`InstructionsLoaded` hook 可以記錄到底哪些指示檔被載入、什麼時候、為什麼。

### CLAUDE.md 太大

- `/doctor` 會**幫已進版控的 CLAUDE.md 提出精簡建議**：砍掉 Claude 可以自己從 codebase 推導的東西（目錄結構、相依清單、架構概述），保留陷阱、理由、和跟工具預設不同的慣例。
- 用 path-scoped rules 拆。
- ⚠️ 拆成 `@` imports **只幫助組織，不省 context**。

### `/compact` 之後指示不見了

**專案根目錄的 CLAUDE.md 會在壓縮後從磁碟重讀並重新注入。** 子目錄的 nested CLAUDE.md **不會**自動重注入，要等下次讀那個子目錄的檔案。

只在對話裡講過的指示會消失 → 想留就寫進 CLAUDE.md。

---

## 🔗 相關筆記

- [[05-權限模式與安全]] — 上一步
- [[07-Skills與斜線指令]] — 下一步：比 CLAUDE.md 更省 context 的做法
- [[09-Hooks自動化]] — 「一定要發生」的事寫這裡
- [[13-實戰-套用在兩個repo]] — 你兩個 repo 的 CLAUDE.md 重構建議

---

*最後更新：2026-08-04*