同樣的事說第三遍，通常代表有個地方沒設計好。

你跟 Claude Code 說「用 pnpm 不要用 npm」，它照做了。第二天開新 session，它又裝了 npm。你說了第二次。第三次。第四次。

這不是 Claude 記性差，是 session 的設計就是這樣——每次啟動都是乾淨的 context，不帶任何記憶。CLAUDE.md 就是專門解決這件事的機制。

兩種記憶，分工不同

Claude Code 有兩套跨 session 的記憶機制，先把它們搞清楚再說怎麼用。

CLAUDE.md：你寫的，Claude 讀的。放進去的是「每個 session 都要成立的規則」——build 指令、coding style、專案架構、「一定要做 X」這種事。每次 Claude Code 啟動都會自動讀進來，不需要你再說一次。

Auto Memory：Claude 寫的，你檢查的。Claude 在工作過程中，如果遇到它判斷「下次會有用」的資訊，就會自動存進去——你糾正了一個它老是用錯的函式、跑了一個奇特的 debug 流程、說了一個這個 repo 特有的習慣，它會把這些記下來。

用一個類比：CLAUDE.md 是你給新同事的 onboarding 文件，auto memory 是那個同事自己記的工作筆記。前者你控制，後者它維護，兩個都在每次 session 開始時被讀進來。

最快的開始：/init

新專案第一步，在 terminal 跑 /init。

Claude 會分析你的 codebase，然後自動生成一份 CLAUDE.md，裡面有它發現的 build 指令、測試指令、專案結構和 convention。不是空白樣板，是基於你的實際 repo 產出的內容。

如果想要更互動的設定流程，在環境變數加 CLAUDE_CODE_NEW_INIT=1，然後跑 /init。Claude 會問你要設定哪些東西（CLAUDE.md、Skills、Hooks），然後用 subagent 探索 codebase，填完空白再給你確認，才正式寫進去。

生成的初始版本跑一個禮拜，遇到什麼地方 Claude 搞錯了或需要補充，就加進去。

CLAUDE.md 要放什麼、不放什麼

CLAUDE.md 每次 session 都會被讀進 context window，佔的是你的 token budget。所以不是什麼都放。

放進去的東西，要能回答這個問題：「一個完全不認識這個專案的新同事，需要知道什麼才能開始工作？」

適合放的：

  • Build 和 test 指令（npm test、pnpm run dev、指定環境變數的方式）
  • 不能踩的地雷（「不要直接 push 到 main」、「所有 API 呼叫必須有 error handling」）
  • 架構說明（「API handler 在 src/api/handlers/」、「shared utils 在 lib/」）
  • 你反覆糾正過的事（「用 2 空格縮排」、「test file 命名規則是 *.spec.ts」）

不適合放的：

  • 只有某個功能才用到的說明（改成 .claude/rules/ 的 path-scoped 規則）
  • 一次性任務的流程（改成 Skills，只在需要的時候載入）
  • 超過 200 行的大段落（切短、或拆到子目錄的 CLAUDE.md 裡）

200 行是個實用的 threshold。超過這個長度，Claude 對後面內容的遵循度會明顯下降，因為它在 context 裡「讀」這個文件跟人讀一樣——開頭比結尾可靠。

四個地方，四種範圍

CLAUDE.md 可以放在不同位置，每個位置的作用範圍不同：

**/Library/Application Support/ClaudeCode/CLAUDE.md**（macOS）或 **/etc/claude-code/CLAUDE.md**（Linux）：公司/組織層級，IT 部署，所有用戶都會讀到，不能被個人設定覆蓋。適合放公司的 coding policy、合規要求。

**./CLAUDE.md 或 ./.claude/CLAUDE.md**：專案層級，check 進 git，整個 team 共享。適合放專案的架構、coding standard、共用 workflow。

**~/.claude/CLAUDE.md**：個人層級，套用到你所有專案。適合放你的個人偏好——用哪個 formatter、喜歡的命名習慣、你自己的 shortcut。

**./CLAUDE.local.md**：個人 + 特定專案，加進 .gitignore 不 commit。適合放你本機的 sandbox URL、測試資料位置、你個人的 workaround。

多個位置同時存在的時候，Claude 會全部讀進來，更具體的位置優先於更廣的位置。

.claude/rules/ — 把規則拆成模組

專案大了之後，一個 CLAUDE.md 會變得很臃腫。.claude/rules/ 讓你把規則拆成多個 topic 檔案，每個檔案一個主題：

1
2
3
4
5
6
.claude/
├── CLAUDE.md
└── rules/
    ├── testing.md      # 測試相關規則
    ├── api-design.md   # API 設計規範
    └── security.md     # 安全性要求

更有用的是 path-scoped rules——在 markdown 檔案最上面加 YAML frontmatter，指定這個規則只在 Claude 處理哪些路徑下的檔案時才載入：

1
2
3
4
5
6
7
8
---
paths:
  - "src/api/**/*.ts"
---
# API 規範
- 所有 endpoint 必須有 input validation
- 用標準 error response format
- 加 OpenAPI 文件

這樣做的好處是：處理 src/api/ 裡的檔案時才讀這些規則，處理前端元件時不佔 context。對大型 monorepo 特別有用。

Auto Memory：讓 Claude 自己記

Auto memory 預設是開的。你不需要特別設定，Claude 會自己決定什麼值得記。

記的東西存在 ~/.claude/projects/<project>/memory/MEMORY.md 裡——以 git repo 為單位，同一個 repo 的所有 worktree 共享同一份 memory。

每次 session 開始，MEMORY.md 的前 200 行（或 25KB）會被載入。超過的部分 Claude 會在需要時才去讀。

想看 Claude 到底記了什麼，跑 /memory。這個指令會列出所有已載入的 CLAUDE.md、CLAUDE.local.md、rules 檔案，還有 auto memory 的位置，讓你直接開來看和編輯。

如果 Claude 在 session 裡說「remember that…」或者你直接說「記下來，這個 repo 用 pnpm」，它會把這個資訊寫進 auto memory，下次 session 自動帶著這個知識進來。

一個常見的坑

/compact 之後，對話歷史被壓縮，你在 chat 裡說過的一些指令或偏好會不見。但 CLAUDE.md 不受影響——compact 之後 Claude 會重新讀一次 CLAUDE.md，注入到新的 context 裡。

如果你在 chat 裡說過某件重要的事，然後跑了 compact，那件事就不見了。解法是：重要的事直接寫進 CLAUDE.md，不要只說在 chat 裡。

下一步

CLAUDE.md 和 auto memory 解決的是「背景知識」問題——讓 Claude 知道這個專案的設定和慣例。

如果你有「特定工作流程」需要自動化，比如一鍵跑完 lint + test + PR description 生成，那是 Skills 的範疇。如果你需要在 Claude 執行某些指令之前自動攔截，那是 Hooks。

背景知識、工作流程、執行攔截——這三層加在一起，才是 Claude Code 完整的自訂化系統。CLAUDE.md 是最基礎的那一層，從這裡開始設定，之後的東西才有地方長。

原文來源：How Claude remembers your project - Claude Code Docs
參考來源：Claude Code in Action - Anthropic Academy