Andrew的筆記園地

閱讀時間約 11 分鐘

⬇ MD

06 - CLAUDE.md 與記憶系統

← 05-權限模式與安全 | 00-Index | 下一篇 → 07-Skills與斜線指令

兩套記憶系統

每個 session 都從空白的 context 開始。有兩個機制把知識帶過去：

CLAUDE.mdAuto memory
誰寫的你Claude 自己
內容指示與規則學到的東西與模式
範圍專案 / 使用者 / 組織每個 repo 一份，worktree 共用
載入每個 session 全部載入每個 session（前 200 行或 25KB）
用來放程式規範、工作流程、專案架構build 指令、除錯心得、Claude 發現的偏好

🔴 兩者都是「上下文」不是「強制設定」。 Claude 讀了會盡量遵守，但不保證。要無論如何都擋下某個動作，用 PreToolUse hook。

CLAUDE.md 放哪裡

按載入順序（範圍由寬到窄，越後面越接近你、越晚被讀到）：

範圍位置用途
Managed policymacOS /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL /etc/claude-code/CLAUDE.md
Windows C:\Program Files\ClaudeCode\CLAUDE.md		組織層級，個人設定無法排除
User~/.claude/CLAUDE.md你所有專案的個人偏好
Project./CLAUDE.md 或 ./.claude/CLAUDE.md團隊共享，進版控
Local./CLAUDE.local.md個人的專案偏好，要加進 .gitignore

載入規則（很重要）

  • Claude Code 從目前工作目錄往上走，每一層檢查 CLAUDE.md 和 CLAUDE.local.md。
  • 全部串接進 context，不是互相覆蓋。
  • 順序是從檔案系統根目錄往下到你的工作目錄——所以離你啟動位置越近的越晚被讀到。
  • 同一層裡 CLAUDE.local.md 接在 CLAUDE.md 後面。
  • 子目錄裡的 CLAUDE.md 不會在啟動時載入，而是在 Claude 讀到那個子目錄的檔案時才載入。

👉 實務結論：一定要 cd 到 repo 根目錄再開 claude，否則專案的 CLAUDE.md 讀不到。用 /context 確認 Memory files 裡有它。

怎麼寫才有效

官方三條原則：

大小：每個 CLAUDE.md 目標 200 行以內。太長吃 context 而且降低遵守率。

⚠️ 你的 Obsidian-med-note/CLAUDE.md 和 Taiwan_IM_board/CLAUDE.md 都遠超過 200 行。這是刻意的取捨（醫學安全規則不能省），但值得知道代價：越長，個別規則被遵守的機率越低。 可以考慮的優化：把「只在特定情境用得到」的段落搬去 .claude/rules/（路徑限定）或 skill（用到才載入）。例如 vault 的 §8 語言學習筆記、§9 理財區，完全可以做成 path-scoped rules。

結構：用 markdown 標題和條列分組。

具體：寫得能驗證。

  • ✅「用 2 空格縮排」 ❌「格式弄好」
  • ✅「commit 前跑 npm test」 ❌「測試你的變更」

一致：兩條規則互相矛盾時，Claude 可能任意挑一條。定期檢查有沒有過時或衝突的指示。

/init 產生起始檔

/init

Claude 分析 codebase，產出含 build 指令、測試方式、專案慣例的 CLAUDE.md。已經有的話它會建議改進而不是覆蓋。

/init 還會讀 Cursor rules（.cursor/rules/、.cursorrules）和 Copilot rules（.github/copilot-instructions.md）並整合。

設 CLAUDE_CODE_NEW_INIT=1 可以開互動式多階段流程：問你要設哪些東西（CLAUDE.md / skills / hooks）、用 subagent 探索、追問補缺、最後給你一份可審閱的提案才寫檔。

匯入其他檔案（@ 語法）

See @README for project overview and @package.json for available npm commands.
 
# Additional Instructions
- git workflow @docs/git-instructions.md
  • 相對路徑是相對於含這個 import 的檔案，不是工作目錄。
  • 可以遞迴匯入，最多 4 層。
  • 想在 CLAUDE.md 裡提到路徑但不匯入 → 用反引號包起來：`@README` 是純文字，@README 會匯入。
  • 匯入的檔案在啟動時一起載入 context，所以拆檔案有助於組織但不會省 context。

⚠️ 外部匯入的警告：專案層級 memory 檔裡，路徑解析到工作目錄外的匯入算「external」。第一次遇到時 Claude Code 會跳確認對話框列出那些檔案。這是在保護你不被別人 commit 進共享專案的東西影響。使用者層級（~/.claude/）的匯入是你自己寫的，不跳。

AGENTS.md 怎麼辦？

Claude Code 讀 CLAUDE.md，不讀 AGENTS.md。 如果你的 repo 已經有 AGENTS.md 給別的 agent 用（例如 Codex），建一個 CLAUDE.md 匯入它：

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

也可以用 symlink（ln -s AGENTS.md CLAUDE.md），但 Windows 建 symlink 要管理員權限或開發者模式，建議用 @AGENTS.md 匯入。

💡 你的 Obsidian-med-note 同時有 AGENTS.md 和 CLAUDE.md。如果兩份內容有重疊，考慮讓 CLAUDE.md 用 @AGENTS.md 匯入共通部分，只在下面加 Claude 專屬規則——避免兩份漂移。

.claude/rules/（路徑限定規則）⭐

大專案可以把指示拆成多個檔案：

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

殺手功能是路徑限定——用 YAML frontmatter 的 paths：

---
paths:
  - "理財(FIN)/**/*.md"
---
 
# 理財筆記規則
 
- 專有名詞**中英並列**（與醫學筆記的「一律英文」相反）
- 財務數字絕不捏造，一律 web 查證權威來源並標查證日
- `transactions.csv` 是唯一真相，報酬率由 compute.py 算，不手填
- 不要在本地跑 compute.py（proxy 擋 Yahoo Finance）

這樣這段規則只有在 Claude 碰理財資料夾的檔案時才進 context，平常不佔位置。

Glob 語法：

Pattern比對
**/*.ts任何目錄下的所有 TypeScript 檔
src/**/*src/ 底下所有檔案
*.md專案根目錄的 markdown
src/**/*.{ts,tsx}大括號展開多副檔名

沒有 paths 的 rule 檔會無條件在啟動時載入，優先級跟 .claude/CLAUDE.md 一樣。

使用者層級規則放 ~/.claude/rules/，先於專案 rules 載入（所以專案 rules 優先級較高）。

🔴 這是你最該做的一個優化。 把 vault 的 CLAUDE.md 從約 200 行的醫學核心規則 + 一堆情境規則，重構成：

  • CLAUDE.md：§0 三條鐵律、§1 語言硬規則、§3 wiki SOP、§5 git（永遠要在 context 裡的）
  • .claude/rules/lang-notes.md（paths: 語言/**）：§8
  • .claude/rules/finance.md（paths: 理財(FIN)/**）：§9
  • .claude/rules/quartz.md（paths: **/*.md）：§6 圖片與 YAML 規則

效果：主檔案變短 → 核心醫學規則的遵守率上升。

Auto memory（Claude 自己記的）

Claude 邊工作邊幫自己記筆記：build 指令、除錯心得、架構筆記、程式風格偏好、工作習慣。它不是每個 session 都存，而是判斷「這件事以後用得到嗎」。

預設是開的。 關掉：/memory 裡有開關（寫進 ~/.claude/settings.json 的 autoMemoryEnabled），或環境變數 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

存在哪：~/.claude/projects/<project>/memory/

  • <project> 由 git repo 推導，所以同一個 repo 的所有 worktree 和子目錄共用一份
  • 結構是一個 MEMORY.md 索引 + 若干主題檔（debugging.md、api-conventions.md…）
  • 只有 MEMORY.md 的前 200 行 / 25KB 會在每個 session 開頭載入；主題檔是 Claude 需要時才讀

機器本機的，不跨機器、不進雲端 session。

看和編輯：

/memory

💡 你說「以後 PMID 一律要查證」這種話時，Claude 會把它存進 auto memory。要進 CLAUDE.md 的話要明講：「把這條加到 CLAUDE.md」。

排查：「Claude 沒照我的 CLAUDE.md 做」

官方給的除錯步驟：

  1. 跑 /context，看 Memory files 清單裡有沒有你的檔案。沒有 = Claude 根本看不到。
  2. 確認那份 CLAUDE.md 在會被載入的位置（見上面的載入規則）。
  3. 把指示寫得更具體。
  4. 找互相矛盾的指示——跨多份 CLAUDE.md 檢查。

如果那條指示是「必須在某個時間點執行」的（例如每次 commit 前、每次改檔後）→ 寫成 hook，不要寫在 CLAUDE.md。

想在 system prompt 層級下指示 → --append-system-prompt（但每次呼叫都要帶，比較適合腳本）。

💡 進階除錯：InstructionsLoaded hook 可以記錄到底哪些指示檔被載入、什麼時候、為什麼。

CLAUDE.md 太大

  • /doctor 會幫已進版控的 CLAUDE.md 提出精簡建議：砍掉 Claude 可以自己從 codebase 推導的東西（目錄結構、相依清單、架構概述），保留陷阱、理由、和跟工具預設不同的慣例。
  • 用 path-scoped rules 拆。
  • ⚠️ 拆成 @ imports 只幫助組織，不省 context。

/compact 之後指示不見了

專案根目錄的 CLAUDE.md 會在壓縮後從磁碟重讀並重新注入。 子目錄的 nested CLAUDE.md 不會自動重注入，要等下次讀那個子目錄的檔案。

只在對話裡講過的指示會消失 → 想留就寫進 CLAUDE.md。

🔗 相關筆記

最後更新：2026-08-04

關係圖譜

反向連結