使用記憶機制

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

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

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

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

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

如果你在 CLAUDE.md 寫：

## Security

- Never read `.env` files.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. CLAUDE.md 應該放在哪裡

位置決定作用域。

作用域             位置
----------------   --------------------------------------------------
组织级             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 路徑會整體移動到那個目錄下。排障時要先確認這一點，否則你可能一直在看錯誤的配置目錄。

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

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

適合寫入：

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

不適合寫入：

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

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

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

有效的記憶有三個特點：

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

弱規則長這樣：

## Coding

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

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

更好的寫法是：

## 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 不能靠猜的關鍵事實。

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

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

/init

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

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

CLAUDE_CODE_NEW_INIT=1 claude

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

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

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

## 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 適合組織內容，但它不會減少上下文。被匯入的內容仍然會在啟動時展開並進入上下文。

9. AGENTS.md 怎麼相容

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

如果一個儲存庫已經有 AGENTS.md，更穩的方式是新建一個 CLAUDE.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 說明。

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

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

• CLAUDE.md
• CLAUDE.local.md

假設你在這個目錄啟動：

/repo/apps/web

可能載入：

/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 後面。也就是說，越靠近啟動位置，越晚進入上下文，通常更容易影響最終行為。

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

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

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

如果你在 /repo 啟動：

/repo/CLAUDE.md
/repo/frontend/CLAUDE.md
/repo/backend/CLAUDE.md

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

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

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

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

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

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

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

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 也會被跳過。

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

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

推薦結構：

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 處理匹配檔案時載入：

---
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/** 有寫作和連結規則。

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

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

~/.claude/rules/

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

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

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

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

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

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

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

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

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

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

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

官方提供 claudeMdExcludes：

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

建議放在：

.claude/settings.local.json

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

注意兩點：

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

17. block HTML comments 會被剝離

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

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

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

## Build Commands

- Use `pnpm build` before release.

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

18. Auto memory 預設開啟

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

你可以用三種方式控制：

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

關閉示例：

{
  "autoMemoryEnabled": false
}

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

19. Auto memory 存在哪裡

預設位置是：

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

目錄裡通常有：

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 寫：

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

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

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

20. MEMORY.md 不是無限載入

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

MEMORY.md

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

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

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

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

21. /memory 是排障入口

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

/memory

官方說明 /memory 可以：

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

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

Remember that this project uses pnpm, not npm.

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

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

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

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

需求                                      放哪里
---------------------------------------   --------------------------------
所有人每次都要知道的项目规则              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。

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

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

適合寫進 managed CLAUDE.md：

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

不適合只寫在 managed CLAUDE.md：

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

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

24. /compact 後為什麼像忘了

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

/compact

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

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

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

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

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 都傳入，更適合指令碼和自動化，不適合作為普通互動專案的長期規則。

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

直接執行：

/memory

然後開啟 auto memory folder。

Auto memory 是普通 Markdown，你可以：

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

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

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

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

最小可用版本長這樣：

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

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
• Explore the .claude directory
• Claude Code settings
• How Claude Code works