03 · 怎麼記住你的習慣

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

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）：構建命令、測試命令、部署流程

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

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

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

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

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

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

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 實際讀取那個目錄下的檔案時按需載入。詳見官方載入順序文件。

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

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

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

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

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

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 在對話中自動識別哪些資訊值得記住，分類存到持久檔案裡。下次啟動新會話時，這些筆記自動可用。

存放位置：

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

5. 怎麼判斷什麼放哪？

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

📜 規則 → CLAUDE.md

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

典型內容：

• 技術堆疊宣告（用 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 本應知道的專案規則
• 你反覆在對話裡解釋同一個流程
• 新團隊成員需要同樣的上下文才能上手

💡 經驗 → Auto Memory

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

典型內容：

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

怎麼寫：

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

怎麼查：

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

🔍 程式碼裡有 → 不存

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

典型內容：

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

為什麼不存：

• 重複存 = 浪費上下文 token + 容易跟程式碼不同步
• Claude 需要時直接讀就行——它在你電腦上（01 篇拆過）
• 資訊源唯一才不會自相矛盾

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

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

場景 A：專案用 Next.js 14 + TypeScript + Prisma，所有 API 必須返回 { data, error } 格式。

場景 B：你昨天發現 Claude 總是把測試 mock 資料庫——你糾正後說"以後所有測試都連真實測試庫"。

場景 C：專案原始碼結構（src/app/ / src/components/ / src/api/handlers/ ...）。

📌 看答案

• 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 能直接讀到？是 → 不存。

6. 完整的畫面

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

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

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

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

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

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

常見原因：

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

排障 2 · 讓指令更具體

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

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

排障 3 · 檔案超過 200 行

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

解法：

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

排障 4 · 多個 CLAUDE.md 互相沖突

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

解法：

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

排障 5 · /compact 後指令好像沒了

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

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

8. 檢驗你真懂了嗎

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

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
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

官方資料

• How Claude remembers your project
• Explore the .claude directory

接下來去哪

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