CLAUDE.md 與工作記憶

5.1　先建立觀念：它有兩種記憶

先講一個你一定會遇到的狀況：每次你開一段新對話，Claude 的腦袋都是「一張白紙」。上一段對話講過的事，它不會自動帶到下一段。這不是它故障，是它本來就這樣設計的。

那要怎麼讓它「跨對話」記得事情？靠兩個機制，而且這兩個機制每次對話一開始就會自動讀進去，不用你每次提醒：

1. CLAUDE.md（你寫的）：一張你親手寫下的便利貼，把專案的規矩、常用指令、你的偏好寫進去。它每次開工都先看一遍。
2. 自動記憶（它自己寫的）：Claude 一邊幫你做事，一邊把學到的東西自己記下來——像是這個專案怎麼跑測試、上次踩過什麼坑、你喜歡什麼程式風格。這個你完全不用動手，它自己來。

5.2　最快上手：用 /init 生成你的第一份 CLAUDE.md

你可能會想：「便利貼聽起來要寫好多字，我又不知道該寫什麼。」別擔心，有一個指令能幫你生出第一版——你只要在 Claude 裡打 /init，它會自己看一遍你的專案，幫你寫好一份起始的 CLAUDE.md。你之後再慢慢補就好。下面手把手帶你做一次。

1. 1
   ✋動手做

   先進到 Claude 裡

   在你的專案資料夾裡打開終端機，輸入 claude 按 Enter，進到 Claude 的對話畫面（這個第 3 章學過）。

   claude

   複製
2. 2
   ✋動手做

   輸入 /init 按 Enter

   在對話框裡直接打下面這個指令，按 Enter。注意開頭那條斜線不要漏掉。

   /init

   複製
3. 3
   ✋動手做

   看它產生 CLAUDE.md

   它會花一點時間讀你的專案，然後在資料夾根目錄產生一個 CLAUDE.md 檔。產生過程中，它通常會把整理出來的內容顯示給你看。如果這個資料夾「已經有」CLAUDE.md，/init 不會直接覆蓋掉它，而是改成「建議你可以補哪些東西」，原本寫好的內容不會被洗掉。

   ✅ 預期會看到

   # 它會在你的資料夾裡建立這個檔，並大致回報：
   Created CLAUDE.md

   複製
4. 4

   打開來看看，再慢慢補

   用你習慣的編輯器打開那個 CLAUDE.md，看它幫你寫了什麼。這只是「起始版本」——哪裡寫得不夠、或它漏掉的規矩，你隨時可以自己加。怎麼寫得好，下一節 5.3 給你範本。

有個好用的小知識：如果你的專案原本就留有其他工具寫的規矩檔——像 AGENTS.md、.cursorrules、.devin/rules/、.windsurfrules 這些——/init 執行時會自動偵測到，把裡面的內容一併讀進去、整合進它幫你寫的 CLAUDE.md 草稿。換句話說，從別的工具搬過來的專案，舊規矩不會平白消失。

5.3　一份好的 CLAUDE.md 該寫什麼

知道怎麼生出檔案了，那到底該往裡面寫什麼？給你一個超好用的判斷標準：

凡是「你每次都得重新跟它解釋一遍」的東西，就寫進去。換個更生活化的說法——如果一個新來的同事，要看了才會知道，那就值得寫。

照這個標準，最該寫的通常是這幾類：常用指令（怎麼安裝、怎麼跑測試、怎麼啟動）、程式風格（縮排幾格、命名規則）、專案結構（哪個資料夾放什麼）、「永遠要做 X」的規則，還有同樣重要的——「不要做的事」。

下面是一份簡單的範本，你可以直接照抄改成自己的。看不懂裡面每一行也沒關係，重點是感受一下「大概長這樣、分這幾段」。

# 專案說明
這是一個線上書店的後端服務。

## 常用指令
- 安裝套件：npm install
- 跑測試：npm test
- 本機啟動：npm run dev

## 程式風格
- 用 2 個空格縮排
- 變數用駝峰式命名（camelCase）

## 不要做的事（Don't）
- 不要直接改 migrations 資料夾
- 不要把密碼或金鑰寫死在程式碼裡

5.4　黃金守則：邊用邊補，而且保持簡短

CLAUDE.md 不是寫一次就收工的東西，它會跟著你和專案一起長大。這裡有兩條 Claude Code 團隊自己在用的守則，記住就好：

第一條，邊用邊補。每次它做錯、你糾正了它，就順手把「這次學到的規矩」補一條進 CLAUDE.md。下次它就不會再犯同樣的錯。日積月累，這份檔會變成你專案的「累積知識庫」——越用越聰明。

第二條，保持簡短。這份檔每次對話都會被「整份」讀進去。如果它太長太雜，會把 Claude 的記憶空間吃掉一大半，正事都還沒開始，腦容量就先滿了。一個好抓的標準是：盡量控制在 200 行以內。

5.5　進階筆記本：路徑限定規則與跨檔案匯入

上一節提到，太籠統或太局部的東西都不該硬塞進 CLAUDE.md。這裡把「精準拆檔」這件事再往下教兩招：一招讓某份規矩只在你真的碰到相關檔案時才登場，另一招把好幾份檔案正式串在一起當成一份用。兩招聽起來有點像，行為卻完全不同，分清楚能少走不少冤枉路。

只在你踩進那個資料夾才生效：.claude/rules/

在專案裡建一個 .claude/rules/ 資料夾，裡面每份 .md 檔都是一條獨立的規則，Claude Code 會遞迴掃描整個資料夾（含子資料夾）。這些規則檔分成兩種行為，差別就在檔案開頭有沒有寫 paths:：

比如你只想讓某份規則在動到 API 程式碼時才出現：

---
paths:
  - "src/api/**/*.ts"
---

# API 開發規則
- 每支 API 端點都要做輸入驗證
- 統一用專案的錯誤回應格式
- 補上 OpenAPI 文件註解

paths: 底下可以放好幾條規則，也支援大括號同時比對多種副檔名：

paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"

跟 CLAUDE.md 一樣，.claude/rules/ 也有個人層版本：放在 ~/.claude/rules/ 底下的規則會套用到你所有專案，載入順序排在專案層規則之前（衝突時專案層優先）。這個資料夾也支援 symlink，可以把同一套規則庫串連進好幾個專案，不用每個 repo 都複製貼上一份——就算不小心接成循環 symlink，系統也會自動偵測、不會卡死。

把好幾份檔案正式串成一份：@ 匯入語法

另一招是 @ 匯入語法——在 CLAUDE.md（或任何會被讀進 context 的檔案）裡寫 @路徑，Claude Code 就會把那個路徑指到的檔案整個接進來，當成同一份文件的延伸：

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

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

有個容易搞混的地方：@ 後面的相對路徑，是相對「寫這行 @ 的那個檔案」去解析，不是相對你目前的工作目錄。它也支援遞迴——被匯入進來的檔案裡如果自己又寫了 @，會繼續往下展開，官方頁面目前明載的上限是4 層（網路上另有資料寫 5 層，實際以官方頁面為準，這類數字版本間可能會調整）。如果你只是想在句子裡「提到」某個檔名、不想觸發匯入，用反引號包起來就好，像 `@README`——匯入解析本來就會跳過反引號與程式碼區塊裡的內容。

第一次在專案裡遇到匯入專案資料夾以外的檔案（例如上面 @~/.claude/my-project-instructions.md 這種指向個人目錄的路徑），Claude Code 會跳出一個核准對話框，列出它打算匯入哪些檔案讓你確認。

@ 匯入還有一個很實用的場景：橋接既有的 AGENTS.md。Claude Code 本身只讀 CLAUDE.md，不會主動去讀 AGENTS.md——如果專案已經有一份給其他 agent 工具用的 AGENTS.md，不想整份複製貼上再維護兩次，可以讓 CLAUDE.md 直接匯入它：

@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

這樣主要內容維持單一來源，下面再補幾行 Claude Code 專屬的細節就好。另一個做法是直接建 symlink：ln -s AGENTS.md CLAUDE.md，讓兩個檔名指向同一份內容——不過 Windows 建立 symlink 需要系統管理員權限或開啟開發者模式，官方建議 Windows 環境還是改用上面的 @ 匯入寫法比較省事。（Codex CLI 的 AGENTS.md 怎麼寫，本章最後的對照連結會帶你去看。）

5.6　它自己也會記：自動記憶怎麼存、怎麼開關

講完「你寫的」便利貼，換講「它自己記的」筆記。這部分最舒服的地方是：你什麼都不用寫。

Claude 一邊幫你工作，會一邊把學到的東西自己存起來——存在一個叫 MEMORY.md 的檔案裡，每次對話開始時自動帶前段內容進來。你也可以隨時開啟或關掉這個功能。

那它記了什麼、記得對不對，你想看看怎麼辦？打一個指令就能查、也能改：

💡 建議執行：查看 / 編輯它記了什麼

/memory

打 /memory，它會把目前記下的內容攤開給你看，你可以一條一條檢查，覺得記錯了、或不想讓它記某件事，當場改掉就行。

還有一招更直接：你可以直接命令它記。例如打一句「記住：我們這個專案用 pnpm，不是 npm。」它就會把這條存進筆記，以後不用你再三叮嚀。

互動模式下還有個更快的手勢：打單獨一個 # 開頭，把想記的一句話接在後面，就能快速把它存進記憶（存的位置是專案層或個人層的 CLAUDE.md，這是你手動觸發的動作，跟自動記憶「它自己判斷該記什麼」不一樣）。

再來是「它存在哪」跟「怎麼關掉」。自動記憶實際放在你電腦裡的 ~/.claude/projects/<專案代號>/memory/ 資料夾，這個「專案代號」是依你的 git repo 推算出來的——同一個 repo 底下不管你開幾個 worktree、切到哪個子目錄，用的都是同一份自動記憶；如果這個資料夾根本不在 git repo 裡，就改用專案的根目錄本身當代號。它是純本機的東西，不會幫你同步到別台電腦，換一台機器工作，記憶要重新累積。

自動記憶預設是開著的。想關掉，最直覺的方式是在 /memory 介面裡切換；想要更持久或更自動化的關法，還有兩個選項：

這一整套「記憶」的概念其實不只主執行緒有——如果你之後接觸到自訂子代理（subagent），會發現它也能擁有自己專屬、獨立於主執行緒之外的記憶資料夾（在設定檔裡寫 memory: user 或 project），讓它每次被叫出來做同一類工作時越做越上手。這部分等你到第 12 章「自建代理人」會更有感覺，這裡先知道有這條路就好。

5.7　記憶的層級：從組織到你的子目錄

把鏡頭拉遠一點：同樣是「給 Claude 看的規矩」，CLAUDE.md 可以放在好幾個不同的地方，差別在「這條規矩管到多大範圍、誰看得到」。官方文件把它分成四層範疇，依載入順序由廣到窄：

一句話幫你記：組織層＝公司規定，最大最優先；個人層＝你自己的習慣，跟著你走到每個專案；專案層＝這個專案的規矩，跟團隊共用；本機層＝專案裡只屬於你的私房筆記，不進版控。剛開始，你只要會用「專案層」那一份 CLAUDE.md，就足以應付絕大多數情況——之後想把個人偏好跟團隊規矩分開，才需要用到本機層。

同一層不只一份：路徑上的檔案會全部疊加

這四層裡，專案層最容易「不只一份」——尤其是在巢狀資料夾裡工作時（例如 monorepo，根目錄有一份 CLAUDE.md，你實際在裡面某個子套件資料夾啟動 Claude）。這種情況下，Claude Code 會從你目前的工作目錄往上一路找到檔案系統根目錄，把沿路遇到的每一份 CLAUDE.md／CLAUDE.local.md全部串接進 context——不是「後面的蓋掉前面的」，是全部疊加，順序由根目錄排到你的工作目錄，越靠近你啟動位置的檔案排越後面；同一層裡如果 CLAUDE.md 和 CLAUDE.local.md 都有，CLAUDE.local.md 排在後面。

檔案本身都在，不會互相刪除彼此的內容；但如果兩條規則講的是互相矛盾的事，通常越靠近你專案、越晚讀到的那條權重會比較高。這也是為什麼團隊共用規矩盡量放根目錄那份，個人覆寫或例外情況才放到離你實際工作位置比較近的地方。

如果你在很大的 monorepo 裡，常被別的團隊寫的祖先層 CLAUDE.md 干擾（跟你完全無關的規矩，卻每次都跟著載進來），可以用 claudeMdExcludes 設定把它排除掉。這個設定接受一份 glob 清單，比對絕對路徑，可以放在個人層、專案層、本機層任一層的 settings.json：

{
  "claudeMdExcludes": [
    "**/monorepo/other-team/CLAUDE.md"
  ]
}

通常建議寫在你自己的 .claude/settings.local.json，只影響你自己，不動到團隊共用設定。有一點要注意：組織層（Managed）的 CLAUDE.md 沒辦法被排除，不管在哪一層設定 claudeMdExcludes 都一樣——這是刻意設計，組織規定不該讓個別開發者自己關掉。

子目錄的 CLAUDE.md：寫了不代表馬上生效

剛剛講的是「祖先」方向（往上找）。那「子目錄」方向（往下）呢？直覺可能會覺得跟根目錄一樣，一開場就通通讀進去——但不是，這是新手最容易誤踩的一個地雷。

想更精確追蹤「哪個指示檔案什麼時候被載入、為什麼」，有個專門的 hook 事件叫 InstructionsLoaded，能即時記下來，特別適合排查這種「按理說該載入卻還沒觸發」的情境——這屬於第 19 章 Hooks 自動化的範圍，這裡先知道有這個工具存在就好。另外，如果你是用 --add-dir 額外掛載了工作目錄以外的資料夾，Claude Code 預設也不會自動讀那個資料夾的 CLAUDE.md；要一併讀，得加環境變數 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。

5.8　/compact 之後，它還記得多少

工作到一半，對話拉得很長，你可能會跑 /compact 讓 Claude 把歷史記錄摘要精簡一下（這個指令第 14 章會更完整地講）。這裡只回答一個很實際的問題：跟 CLAUDE.md、記憶有關的東西，/compact 之後還在不在？答案是「看情況」，整理成一張表方便查：

會不見的剛好都是「隨選才載入」的那幾種，這跟它們原本「按需局部生效」的設計互相呼應。如果有件事無論如何都不能在 compact 之後消失、不能有任何遺漏的空窗，那已經超出 CLAUDE.md／記憶這套機制的守備範圍——回到本章一開始 5.1 提過的：這時候該用的是 Hook，不是往記憶裡加字。

5.9　它不聽話怎麼辦：排查與眉角

萬一你已經照這章的方法寫好 CLAUDE.md，Claude 卻還是一犯再犯同一個錯——先別急著懷疑自己「是不是寫得不夠兇」。這一節帶你照順序排查，順便說幾個連老手都會踩到的眉角。

1. 先確認它真的有被載入。打 /memory，看看你以為寫好的那份 CLAUDE.md、或某條 path-scoped 規則，有沒有出現在清單裡。沒出現，通常是路徑寫錯、或這條規則根本沒被觸發，回頭檢查前面幾節教的載入條件。
2. 有載入但還是不聽，多半是措辭問題，或規則互相打架。檢查這條規則寫得夠不夠具體，還有沒有跟別份 CLAUDE.md（例如上一節提到的祖先路徑疊加）講的東西互相矛盾。矛盾時，越靠近你專案的那層通常權重比較高，但這只是「通常」，不是保證。
3. 還是搞不定，做一次完全乾淨的隔離測試。有兩個辦法：一是用 claude --safe-mode（v2.1.169 之後的版本才有這個旗標，實際版本門檻以 claude --help 為準），開機時直接關掉所有客製化——CLAUDE.md、skills、plugins、hooks、MCP、自訂指令與 agent 全部關掉，只留登入、模型、內建工具、權限系統正常運作；二是把環境變數 CLAUDE_CONFIG_DIR 指到一個空資料夾，開一個完全不受任何既有設定干擾的全新 session。兩種都能幫你排除「是不是某個設定互相打架」，再一項一項加回來，抓出兇手。

💡 建議執行：完全乾淨、不受任何既有設定干擾的測試

# 指到一個空資料夾，等於全新的 Claude Code 環境
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

最後補一個進階備註：上面「CLAUDE.md 只是建議」這件事，在 headless／CI 這種每次呼叫都是全新、彼此獨立的場景裡格外明顯——沒有連續的 session，也就沒有「它讀過 CLAUDE.md」這回事可以依賴。這種情境下有個更直接的工具叫 --append-system-prompt，效果接近把你的指示直接寫進 system prompt 裡（保證等級比 CLAUDE.md 高），代價是每次呼叫都要重新帶上這個參數，比較適合寫進自動化腳本。這是第 20 章 Headless 與 CI 的範圍，這裡你只要知道有這條路就好。