---
title: "使用記憶機制"
description: "Claude Code 的記憶分成 CLAUDE.md 和 auto memory（自動記憶）。學會檔案位置、載入順序、@import、.claude/rules、/memory、claudeMdExcludes 和排障邊界。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

Claude Code 的記憶不是一個神秘資料庫，而是每次會話開始時被裝進上下文的一組說明。你把規則寫清楚，它就少走彎路；你把規則寫亂，它會把混亂也帶進下一次工作。——Aaron

> [!NOTE]
> **這一章用 15 分鐘換什麼**：你已經知道 settings（設定）和 permissions（許可權）管配置與許可權。現在補上另一半：Claude 每次開始時“知道什麼”。讀完你應該能判斷規則該寫進 `CLAUDE.md`、`.claude/rules/`、Skill、settings，還是交給 auto memory（自動記憶）。

## 1. 先劃清邊界：記憶是上下文，不是強制層

新手最容易把三件事混在一起：

- 記憶：告訴 Claude 專案結構、約定、偏好、經驗。
- 配置：告訴 Claude Code 客戶端如何執行，比如 scope（作用域）、環境變數、Hooks、模型、外掛。
- 許可權：控制工具呼叫能不能執行，比如 `Bash`、`Read`、`Edit`、`WebFetch`、MCP 工具。

`CLAUDE.md` 和 auto memory 都屬於第一類。它們會影響 Claude 的判斷，但不會像 `permissions.deny` 那樣強制攔截工具。

如果你在 `CLAUDE.md` 寫：

```md

## Security

- Never read `.env` files.
```

這是一條行為提醒。它有用，但不是安全邊界。

如果你要真的阻止讀取 `.env`，要寫進 settings permissions：

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

> [!IMPORTANT]
> **第一性原理**：記憶讓 Claude 更懂專案；許可權限制 Claude Code 能呼叫什麼工具。不要用記憶承擔安全職責。

## 2. Claude Code 每次啟動會裝載什麼

一個會話開始時，Claude Code 會把多種材料放進上下文視窗：

- 當前對話。
- 系統指令。
- 你啟動位置相關的 `CLAUDE.md` / `CLAUDE.local.md`。
- 規則檔案 `.claude/rules/*.md`。
- auto memory 的入口內容。
- 後續工具讀到的檔案、命令輸出、網頁內容。

可以把它理解成一條啟動流水線：

| 順序 | 載入內容 | 作用 |
|------|----------|------|
| 1 | 當前對話與系統指令 | 建立基礎行為邊界 |
| 2 | 工作目錄相關的 `CLAUDE.md` / `CLAUDE.local.md` | 注入專案、使用者和本地規則 |
| 3 | `.claude/rules/*.md` | 載入通用規則，或在匹配路徑時按需載入 |
| 4 | auto memory 入口內容 | 帶入本機學習記錄 |
| 5 | 工具讀取的新檔案、命令輸出、網頁內容 | 隨任務推進繼續補上下文 |

這裡最關鍵的是：上下文會被消耗。規則越多，佔用越多；規則越模糊，遵循越不穩定。

> [!TIP]
> **不要追求“寫全”**：`CLAUDE.md` 的目標不是把專案百科搬進去，而是把 Claude 每次都必須知道的少數事實寫準。

## 3. 兩套記憶：你寫的，和 Claude 自己寫的

Claude Code 官方把記憶分成兩類。

```text
机制               谁写                 主要用途
----------------   ------------------   ------------------------------
CLAUDE.md          你或团队              项目规则、命令、架构、工作流
auto memory        Claude 自动维护       调试经验、偏好、反复纠正过的事
```

`CLAUDE.md` 更像專案手冊。它適合放穩定、明確、團隊可共享的內容：

- 專案結構。
- 構建、測試、釋出命令。
- 程式碼風格。
- 命名約定。
- 常見工作流。
- 不該靠程式碼自動推斷的團隊規則。

Auto memory 更像 Claude 的本地筆記。它適合記錄 Claude 在工作中學到的東西：

- 某個測試需要本地 Redis。
- 這個專案總是用 `pnpm`，不要用 `npm`。
- 某個模組的除錯入口。
- 你多次糾正過的個人偏好。

> [!WARNING]
> **auto memory 不是團隊規範**：它是本機本專案的學習記錄，不會自動同步到其他機器，也不應該替代提交到儲存庫的專案說明。

## 4. `CLAUDE.md` 應該放在哪裡

位置決定作用域。

```text
作用域             位置
----------------   --------------------------------------------------
组织级             macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
组织级             Linux / WSL: /etc/claude-code/CLAUDE.md
组织级             Windows: C:\Program Files\ClaudeCode\CLAUDE.md
项目共享           ./CLAUDE.md
项目共享           ./.claude/CLAUDE.md
用户全局           ~/.claude/CLAUDE.md
本地个人           ./CLAUDE.local.md
```

選擇方式很直接：

- 所有機器、所有人都必須遵守：組織級 managed `CLAUDE.md`。
- 這個儲存庫所有協作者都應該知道：專案 `CLAUDE.md` 或 `.claude/CLAUDE.md`。
- 只有你自己所有專案都要用：`~/.claude/CLAUDE.md`。
- 只有你自己、當前專案、當前機器要用：`CLAUDE.local.md`。

`CLAUDE.local.md` 應該加入 `.gitignore`。它適合寫本機埠、個人測試賬號名、個人習慣、臨時實驗說明。

如果你設定了 `CLAUDE_CONFIG_DIR`，官方文件裡的 `~/.claude` 路徑會整體移動到那個目錄下。排障時要先確認這一點，否則你可能一直在看錯誤的配置目錄。

> [!CAUTION]
> **不要把個人偏好提交到專案記憶**：你喜歡的編輯器、埠、測試資料、別名，不一定是團隊規則。

## 5. 什麼時候該寫進 `CLAUDE.md`

官方給的判斷很實用：你本來會反覆向 Claude 解釋的東西，就應該沉澱進 `CLAUDE.md`。

適合寫入：

- Claude 第二次犯同一個專案級錯誤。
- 程式碼審查指出它本應知道的約定。
- 新同事也需要知道的啟動、測試、釋出流程。
- 專案結構不明顯，靠檔名很難推斷。
- 某個目錄有強規則，比如 API handler、資料庫遷移、支付邏輯。

不適合寫入：

- 一次性任務背景。
- 長篇會議紀要。
- 金鑰、賬號、token。
- 複雜操作 SOP 的完整正文。
- 只對某個檔案型別生效的規則。
- Claude 自動發現即可的普通程式碼事實。

多步 SOP 更適合做 Skill。只對部分路徑生效的規則，更適合 `.claude/rules/`。

> [!IMPORTANT]
> **目標長度**：官方建議每個 `CLAUDE.md` 目標控制在 200 行以內。超過這個範圍，規則會佔用更多上下文，也更容易互相沖突。

## 6. 怎麼寫一個有效的 `CLAUDE.md`

有效的記憶有三個特點：

- 具體：能被驗證。
- 穩定：下週仍然成立。
- 簡短：每句話都值得進入上下文。

弱規則長這樣：

```md

## Coding

- Write clean code.
- Be careful.
- Follow best practices.
```

這類規則幾乎不可執行。它們聽起來正確，但 Claude 無法穩定判斷“clean”和“best”到底是什麼。

更好的寫法是：

```md

## Project Commands

- Use `pnpm install` to install dependencies.
- Use `pnpm test` before changing files under `src/core/`.
- Use `pnpm build` before opening a pull request.

## Code Conventions

- API handlers live under `src/api/handlers/`.
- Database migrations live under `db/migrations/`.
- Public React components use PascalCase filenames.
- Do not edit generated files under `src/generated/`.

## Workflow

- Before changing payment code, read `docs/payment-flow.md`.
- After editing GraphQL schema, run `pnpm codegen`.
```

這份檔案不追求完整解釋專案，只告訴 Claude 不能靠猜的關鍵事實。

> [!TIP]
> **寫法標準**：用動詞開頭，寫可驗證動作。少寫價值觀，多寫路徑、命令、條件和例外。

## 7. `/init` 可以幫你生成起點

新專案可以直接在 Claude Code 裡執行：

```text
/init
```

官方說明：`/init` 會分析程式碼庫，生成或改進專案 `CLAUDE.md`，通常會包含構建命令、測試命令和專案約定。已有 `CLAUDE.md` 時，它會建議改進，而不是簡單覆蓋。

官方還提供了一個新流程開關：

```bash
CLAUDE_CODE_NEW_INIT=1 claude
```

啟用後，`/init` 會以更互動的多階段方式詢問要設定哪些 artifact，比如 `CLAUDE.md`、Skills、Hooks。它會先探索程式碼庫，再提出可審查的方案。

> [!WARNING]
> **不要盲收 `/init` 的輸出**：它能發現命令和結構，但無法知道團隊真正的約定。生成後要刪掉噪音、補上隱性規則。

## 8. `@import`：拆檔案，不等於省上下文

`CLAUDE.md` 可以用 `@path` 匯入其他檔案：

```md

## Project Context

- See @README.md for product overview.
- See @package.json for script names.
- See @docs/release-checklist.md before release work.
```

關鍵規則：

- 相對路徑按包含 import 的檔案解析，不按當前 shell 工作目錄解析。
- 絕對路徑和 `~` 路徑也可以使用。
- 匯入可以遞迴。
- 最大遞迴深度是 5 層。
- 首次遇到專案外部匯入時，Claude Code 會彈出確認。
- 如果使用者拒絕外部匯入，後續不會繼續讀取那些外部檔案。

拆 import 適合組織內容，但它不會減少上下文。被匯入的內容仍然會在啟動時展開並進入上下文。

> [!IMPORTANT]
> **不要用 import 假裝瘦身**：如果一個規則不需要每次載入，應該改成 path-scoped rule 或 Skill，而不是換個檔名匯入。

## 9. `AGENTS.md` 怎麼相容

官方口徑很明確：Claude Code 讀取 `CLAUDE.md`，不是直接讀取 `AGENTS.md`。

如果一個儲存庫已經有 `AGENTS.md`，更穩的方式是新建一個 `CLAUDE.md` 匯入它：

```md
@AGENTS.md

## Claude Code

- Use plan mode before changing files under `src/billing/`.
- Run `/memory` when debugging instruction loading.
```

這樣其他 agent 仍然讀 `AGENTS.md`，Claude Code 透過 `CLAUDE.md` 讀同一份基礎規則，再追加 Claude-specific 說明。

> [!TIP]
> **相容優先順序**：不要維護兩份互相複製的規則。讓 `CLAUDE.md` 匯入 `AGENTS.md`，再只寫 Claude Code 特有差異。

## 10. 載入順序：越靠近啟動目錄，越晚進入上下文

Claude Code 會從當前工作目錄一路向上查詢：

- `CLAUDE.md`
- `CLAUDE.local.md`

假設你在這個目錄啟動：

```text
/repo/apps/web
```

可能載入：

```text
/repo/CLAUDE.md
/repo/CLAUDE.local.md
/repo/apps/CLAUDE.md
/repo/apps/CLAUDE.local.md
/repo/apps/web/CLAUDE.md
/repo/apps/web/CLAUDE.local.md
```

官方說明的順序是從更高層目錄到當前目錄。同一目錄裡，`CLAUDE.local.md` 接在 `CLAUDE.md` 後面。也就是說，越靠近啟動位置，越晚進入上下文，通常更容易影響最終行為。

這不是“覆蓋”。所有發現的檔案會拼接進上下文。衝突規則仍然是衝突規則。

| 載入順序 | 示例檔案 | 含義 |
|----------|----------|------|
| 1 | `/repo/CLAUDE.md` | 儲存庫根規則先進入上下文 |
| 2 | `/repo/CLAUDE.local.md` | 儲存庫根本地規則跟隨進入 |
| 3 | `/repo/apps/CLAUDE.md` | 更靠近啟動目錄的規則更晚進入 |
| 4 | `/repo/apps/CLAUDE.local.md` | 對應層級的本地規則跟隨進入 |
| 5 | `/repo/apps/web/CLAUDE.md` | 當前啟動目錄規則最後進入 |
| 6 | `/repo/apps/web/CLAUDE.local.md` | 當前目錄本地規則最後進入 |

> [!WARNING]
> **衝突不會自動消失**：上層說用 `npm`，下層說用 `pnpm`，Claude 可能按更近規則執行，也可能在複雜任務裡搖擺。最好的排障不是猜優先順序，而是刪掉衝突。

## 11. 子目錄規則是按需載入的

啟動時，Claude 不會把當前工作目錄下面所有子目錄的 `CLAUDE.md` 都讀進來。

如果你在 `/repo` 啟動：

```text
/repo/CLAUDE.md
/repo/frontend/CLAUDE.md
/repo/backend/CLAUDE.md
```

啟動時會讀 `/repo/CLAUDE.md`。`frontend/CLAUDE.md` 和 `backend/CLAUDE.md` 會在 Claude 讀取對應子目錄檔案時按需載入。

這對大型 monorepo 很重要：你不需要把所有團隊規則都塞進根檔案，也不需要讓前端任務一開始就載入後端全部規則。

> [!TIP]
> **大型儲存庫策略**：根 `CLAUDE.md` 寫全域性最小規則；具體目錄規則放在對應子目錄或 `.claude/rules/`。

## 12. 附加目錄不會預設載入記憶

`--add-dir` 可以給 Claude 額外目錄訪問許可權：

```bash
claude --add-dir ../shared-config
```

但官方說明：預設不會載入這個附加目錄裡的 `CLAUDE.md`。

如果你想同時載入附加目錄裡的記憶檔案，需要設定：

```bash
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
```

這會載入附加目錄中的：

- `CLAUDE.md`
- `.claude/CLAUDE.md`
- `.claude/rules/*.md`
- `CLAUDE.local.md`

如果你用 `--setting-sources` 排除了 local，附加目錄裡的 `CLAUDE.local.md` 也會被跳過。

> [!CAUTION]
> **別把訪問許可權和記憶載入混為一談**：`--add-dir` 讓 Claude 可以訪問目錄，不代表目錄裡的說明自動進入上下文。

## 13. `.claude/rules/`：給大型專案拆規則

當 `CLAUDE.md` 變長，第一反應不應該是繼續加標題，而是把路徑相關規則拆到 `.claude/rules/`。

推薦結構：

```text
your-project/
  .claude/
    CLAUDE.md
    rules/
      code-style.md
      testing.md
      security.md
      frontend/
        react.md
      backend/
        api.md
```

規則檔案是普通 Markdown。官方說明所有 `.md` 檔案會被遞迴發現。

沒有 `paths` frontmatter 的規則，會像 `.claude/CLAUDE.md` 一樣每次載入。

帶 `paths` 的規則，只在 Claude 處理匹配檔案時載入：

```md
---
paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"
---

## API Development Rules

- All API handlers must validate input.
- Use the shared error response format.
- Update OpenAPI comments when adding endpoints.
```

適合用 path rules 的場景：

- `src/api/**` 有介面約定。
- `db/migrations/**` 有遷移規則。
- `packages/mobile/**` 和 `packages/web/**` 使用不同框架。
- `*.test.ts` 必須走固定測試工具。
- `docs/**` 有寫作和連結規則。

> [!IMPORTANT]
> **path rule 不是許可權規則**：它決定什麼時候載入說明，不決定檔案能不能讀寫。檔案訪問邊界仍然由 permissions 和 sandbox 控制。

## 14. user-level rules 與專案規則的關係

你也可以把個人規則放在：

```text
~/.claude/rules/
```

這適合寫個人偏好，例如：

- 所有專案預設先讀 `CLAUDE.md`。
- 回答預設使用簡體中文。
- 程式碼審查預設先列風險。

官方說明：user-level rules 先載入，project rules 後載入，所以專案規則優先順序更高。

這個設計是合理的。你可以有全域性習慣，但專案約定應該能壓過個人習慣。

> [!TIP]
> **個人規則要少而穩**：全域性規則會進入很多專案，寫得越多，越容易和專案規則衝突。

## 15. 規則支援 symlink，但要避免環

`.claude/rules/` 支援 symlink。你可以把一套共享規則維護在一個目錄，然後連結到多個專案：

```bash
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md
```

官方說明 symlink 會正常解析，迴圈 symlink 會被檢測並處理。

這個能力適合個人多儲存庫或組織模板，但不適合把所有規則都做成全域性大包。共享規則越多，越要保持單一職責。

> [!WARNING]
> **共享規則不是越多越好**：能模板化的是基礎約定，專案差異仍然應該留在專案裡。

## 16. `claudeMdExcludes`：跳過不相關的記憶

大型 monorepo 裡，經常會遇到祖先目錄或其他團隊的 `CLAUDE.md` 被載入，結果規則不相關甚至衝突。

官方提供 `claudeMdExcludes`：

```json
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}
```

建議放在：

```text
.claude/settings.local.json
```

原因是排除哪些父級規則，往往和你當前機器、當前工作方式有關，不一定應該提交給團隊。

注意兩點：

- 匹配的是絕對檔案路徑。
- managed policy 的 `CLAUDE.md` 不能被排除。

> [!CAUTION]
> **不要用 exclude 掩蓋真實衝突**：如果團隊都被同一條錯誤規則影響，應該修改規則源頭，而不是每個人各自 local exclude。

## 17. block HTML comments 會被剝離

官方說明：`CLAUDE.md` 裡的 block-level HTML comments 會在注入上下文前被剝離。

這意味著你可以給人類維護者留備註：

```md
<!-- This section is for maintainers and will not enter Claude context. -->

## Build Commands

- Use `pnpm build` before release.
```

這些註釋不會消耗上下文 token。程式碼塊裡的註釋會保留；你直接用 Read 工具開啟 `CLAUDE.md` 時，也仍然能看到註釋。

> [!TIP]
> **維護說明和執行規則分開**：給人看的解釋可以放 HTML comment，給 Claude 執行的規則放正文。

## 18. Auto memory 預設開啟

Auto memory 是 Claude 自己維護的跨會話筆記。官方說明它從 Claude Code v2.1.59 起可用，並且預設開啟。

你可以用三種方式控制：

```text
方式                         用途
--------------------------   --------------------------------
/memory                      会话内查看、编辑、切换 auto memory
autoMemoryEnabled            在项目 settings 里启用或关闭
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1   用环境变量关闭
```

關閉示例：

```json
{
  "autoMemoryEnabled": false
}
```

Auto memory 不會每個會話都寫。Claude 會判斷某條資訊未來是否有用，再決定是否儲存。

> [!IMPORTANT]
> **auto memory 是輔助，不是審計系統**：不要假設 Claude 一定記錄了某個結論，也不要假設它永遠不會記錄你給過的資訊。

## 19. Auto memory 存在哪裡

預設位置是：

```text
~/.claude/projects/<project>/memory/
```

目錄裡通常有：

```text
memory/
  MEMORY.md
  debugging.md
  api-conventions.md
  other-topic-files.md
```

`<project>` 由 git repository 推導。同一個儲存庫裡的不同 worktree 和子目錄會共享同一個 auto memory 目錄。儲存庫外則按 project root 推導。

Auto memory 是機器本地的：

- 不會自動跨機器同步。
- 不會自動進入 GitHub。
- 不會自動進入雲端開發環境。
- 不會替代專案 `CLAUDE.md`。

如果你要改儲存位置，可以在 user settings 寫：

```json
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}
```

官方限制：`autoMemoryDirectory` 必須是絕對路徑或以 `~/` 開頭，並且只接受 policy、user settings 或命令列 `--settings`。不能放在 project/local settings 裡。

這個限制是安全設計：儲存庫不能透過提交專案配置，把你的個人記憶重定向到敏感路徑。

> [!CAUTION]
> **不要同步整個 auto memory 目錄**：裡面是 Claude 的本地學習筆記，可能包含除錯路徑、命令輸出、偏好和專案細節。團隊共識應該寫入儲存庫的 `CLAUDE.md`。

## 20. `MEMORY.md` 不是無限載入

Auto memory 目錄裡的入口檔案是：

```text
MEMORY.md
```

官方說明：每次會話開始只載入 `MEMORY.md` 的前 200 行，或前 25KB，取較小者。

詳細主題檔案不會啟動時全部載入。Claude 會在需要時用標準檔案工具按需讀取，比如：

- `debugging.md`
- `architecture.md`
- `test-fixtures.md`
- `api-conventions.md`

這也是為什麼 `MEMORY.md` 應該像索引，而不是長文件。

> [!TIP]
> **auto memory 的好結構**：`MEMORY.md` 保持短索引，細節拆到 topic files。否則超過閾值的內容一開始就不會進入上下文。

## 21. `/memory` 是排障入口

當你不確定 Claude 到底讀了什麼，先執行：

```text
/memory
```

官方說明 `/memory` 可以：

- 列出當前會話載入的 `CLAUDE.md`。
- 列出 `CLAUDE.local.md`。
- 列出 rules 檔案。
- 切換 auto memory。
- 開啟 auto memory 資料夾。
- 選擇檔案用編輯器開啟。

你也可以直接讓 Claude 記住某條經驗：

```text
Remember that this project uses pnpm, not npm.
```

如果你想把內容寫進 `CLAUDE.md`，表達要更明確：

```text
Add this rule to CLAUDE.md: use pnpm test before editing src/core.
```

> [!IMPORTANT]
> **排障先看 `/memory`**：不要憑感覺判斷 Claude 是否載入了某個檔案。先讓當前會話列出來。

## 22. 記憶、rules、Skill、settings 怎麼選

把內容放錯地方，是 Claude Code 專案越用越亂的主要原因。

```text
需求                                      放哪里
---------------------------------------   --------------------------------
所有人每次都要知道的项目规则              CLAUDE.md
只对某些路径或文件类型生效的规则          .claude/rules/*.md
跨项目个人表达偏好                        ~/.claude/CLAUDE.md 或 ~/.claude/rules/
一次可复用的复杂工作流                    Skill
工具权限、环境变量、Hooks、模型、插件     settings.json
MCP server 连接                            .mcp.json 或 MCP 配置
Claude 从纠正中学到的本机经验             auto memory
企业强制策略                              managed settings 或 managed CLAUDE.md
```

幾個判斷句：

- 要強制執行，用 settings / permissions。
- 要按路徑載入，用 rules。
- 要複用流程，用 Skill。
- 要團隊共享，用 project scope。
- 要個人保留，用 user 或 local scope。
- 要 Claude 自己學，用 auto memory。

> [!TIP]
> **最穩結構**：根 `CLAUDE.md` 保持短；複雜流程做 Skill；路徑差異放 rules；安全邊界放 permissions。

## 23. 組織級 `CLAUDE.md` 和 managed settings 分工

組織可以部署 managed `CLAUDE.md`，讓所有使用者都載入組織級說明。

適合寫進 managed `CLAUDE.md`：

- 公司程式碼風格。
- 資料處理提醒。
- 合規要求說明。
- 程式碼審查原則。
- 內部儲存庫結構說明。

不適合只寫在 managed `CLAUDE.md`：

- 禁止某個工具。
- 禁止讀取某類路徑。
- 強制 sandbox。
- 強制登入方式。
- 強制組織賬號。

這些應該進 managed settings，因為 settings 由客戶端執行，不能靠 Claude 自覺。

> [!IMPORTANT]
> **組織策略分兩層**：行為指導寫 managed `CLAUDE.md`；硬約束寫 managed settings。

## 24. `/compact` 後為什麼像忘了

上下文會填滿，Claude Code 會壓縮舊上下文。使用者也可以執行：

```text
/compact
```

官方說明：專案根 `CLAUDE.md` 會在 compaction 後從磁碟重新讀取並重新注入會話。

但巢狀目錄裡的 `CLAUDE.md` 不會自動全部重新注入。它們需要等 Claude 再次讀取對應子目錄裡的檔案時觸發。

所以 `/compact` 後出現“忘了某條規則”，常見原因是：

- 那條規則只在對話裡說過，沒有寫進 `CLAUDE.md`。
- 那條規則在巢狀目錄 `CLAUDE.md` 裡，但對應目錄還沒重新觸發。
- 規則太模糊或和其他規則衝突。
- 規則來自 auto memory topic file，啟動時沒有直接載入。

> [!WARNING]
> **不要把會話內提醒當長期規則**：重要規則必須落檔案，否則壓縮、恢復、換會話後都可能丟。

## 25. 常見故障：Claude 不聽 `CLAUDE.md`

按這個順序查：

1. 執行 `/memory`，確認檔案真的被列出。
2. 確認你在正確目錄啟動 Claude Code。
3. 檢查是否設定了 `CLAUDE_CONFIG_DIR`。
4. 檢查是否被 `claudeMdExcludes` 排除。
5. 檢查規則是不是太長、太泛、互相沖突。
6. 檢查相關規則是不是 path-scoped，還沒有被觸發。
7. 檢查是否剛 `/compact`，巢狀規則還沒重新載入。
8. 必要時用 `InstructionsLoaded` hook 記錄載入了哪些 instruction files。

如果你想把某段說明提升到系統提示詞層級，官方提到可以用 `--append-system-prompt`。但它需要每次 invocation 都傳入，更適合指令碼和自動化，不適合作為普通互動專案的長期規則。

> [!CAUTION]
> **不要用更強提示詞壓爛規則體系**：先修檔案位置、載入順序和衝突，再考慮 system prompt 級別的注入。

## 26. 常見故障：不知道 auto memory 寫了什麼

直接執行：

```text
/memory
```

然後開啟 auto memory folder。

Auto memory 是普通 Markdown，你可以：

- 讀取。
- 編輯。
- 刪除。
- 拆分 topic。
- 刪除不該保留的敏感內容。

當介面出現 `Writing memory` 或 `Recalled memory`，說明 Claude 正在寫入或讀取 auto memory 目錄。

> [!WARNING]
> **定期審計記憶**：不要把路徑、賬號、內部細節、一次性判斷長期留在 auto memory 裡。

## 27. 一個新專案的推薦落地順序

新專案不要一上來寫大而全的規則。按這個順序收斂：

<Steps>

<Step>
### 專案根執行 `/init`
讓 Claude Code 先掃一遍程式碼庫，生成 `CLAUDE.md` 起點（含構建/測試命令、專案結構推斷）。
</Step>

<Step>
### 刪除自動生成裡的廢話
`/init` 輸出會有"clean code / best practices"這類不可執行規則，直接刪；猜錯的命令路徑也刪。
</Step>

<Step>
### 保留穩定關鍵事實
構建、測試、目錄約定、命名、生成檔案、釋出邊界——這些靠 Claude 自己推斷不穩定的事實留下。
</Step>

<Step>
### 把根 `CLAUDE.md` 控制在 200 行以內
官方建議；超過就拆。
</Step>

<Step>
### 路徑規則拆到 `.claude/rules/`
按 `src/api/**` / `db/migrations/**` 等路徑切，加 `paths` frontmatter 讓規則按需載入。
</Step>

<Step>
### 複雜流程做成 Skill
多步 SOP（如 release checklist、bug triage）放 Skill，不擠進 `CLAUDE.md`。
</Step>

<Step>
### 許可權寫進 settings.json 或 managed settings
安全邊界（不能讀 `.env`、不能 `rm -rf`、不能 push 到 main）走 permissions deny，不靠 `CLAUDE.md` 自覺。
</Step>

<Step>
### 個人偏好放 user/local scope
你的埠、測試賬號、個人習慣走 `~/.claude/CLAUDE.md` 或 `CLAUDE.local.md`，不汙染團隊規則。
</Step>

<Step>
### `/memory` 驗證當前會話載入了什麼
跑一次 `/memory`，確認所有該載入的檔案都在列表裡，沒有意外的祖先或外部規則。
</Step>

</Steps>

最小可用版本長這樣：

```text
your-project/
  CLAUDE.md
  .claude/
    settings.json
    rules/
      testing.md
      security.md
```

> [!TIP]
> **先短後準**：能穩定減少誤操作的 30 行規則，比沒人能維護的 300 行手冊更有價值。

## 28. 自檢清單

學完這一章，你應該能完成這些判斷：

- 我能解釋為什麼記憶不是許可權系統。
- 我能判斷一條規則該放 `CLAUDE.md`、`.claude/rules/`、Skill、settings 還是 auto memory。
- 我知道 `CLAUDE.local.md` 應該 gitignored。
- 我知道 `@import` 會進入上下文，不是省 token。
- 我知道 Claude Code 讀取 `CLAUDE.md`，不是直接讀取 `AGENTS.md`。
- 我知道子目錄 `CLAUDE.md` 是按需載入，不是啟動時全量載入。
- 我知道 `--add-dir` 不會預設載入附加目錄記憶。
- 我知道 auto memory 預設位置和 `MEMORY.md` 啟動載入限制。
- 我能用 `/memory` 排查當前會話到底載入了什麼。
- 我能把安全邊界放進 permissions，而不是隻寫進記憶。

## 29. 術語速查

- `CLAUDE.md`：Claude Code 每次會話載入的長期說明檔案。
- `CLAUDE.local.md`：當前專案的個人本地說明，通常不提交。
- `.claude/CLAUDE.md`：專案級說明的另一種官方位置。
- `.claude/rules/`：可按路徑或主題拆分的規則目錄。
- `paths frontmatter`：控制某條 rule 何時按檔案路徑載入。
- `@import`：在 `CLAUDE.md` 中匯入其他檔案的語法。
- `auto memory`：Claude 自動維護的跨會話本地筆記。
- `MEMORY.md`：auto memory 入口索引檔案。
- `/memory`：檢視、編輯、切換記憶的命令。
- `claudeMdExcludes`：排除某些 `CLAUDE.md` 或 rules 的 settings 欄位。
- `InstructionsLoaded hook`：除錯 instruction 檔案載入的 hook。
- `managed CLAUDE.md`：組織級統一下發的說明檔案。

## 官方來源

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

<Cards>
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/mcp" title="連線 MCP 服務" description="記憶決定 Claude 知道什麼；MCP 決定 Claude 能連線哪些外部工具和資料來源。下一章繼續講連線邊界。" />
  <Card href="/zh-Hant/docs/claude-code/official/01-core-capabilities/permissions" title="管理許可權（上一篇）" description="如果你還沒分清記憶和許可權，先回到 permissions：那一章講真正的工具呼叫邊界。" />
  <Card href="/zh-Hant/docs/claude-code/understanding/03-memory" title="深度理解：記憶與上下文" description="想繼續理解為什麼上下文會影響 AI 程式設計質量，可以讀理解篇裡的 Memory / Context。" />
</Cards>
