這是 Claude Code 系列的進階篇。建議先閱讀： 📖 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（上）

---

🎯 前言

你有沒有遇過這個情境？

你：commit message 不要加 Co-Authored-By
Claude：好的，我不加。

（兩天後，新的 session）

你：幫我 commit
Claude：git commit -m "fix: ... 

Co-Authored-By: Claude ..."
你：我不是說過不要加嗎？

問題在於 LLM 的對話是無狀態的。上一次 session 說過的事，這次 session 完全不記得。

CLAUDE.md 解決了一部分——你可以把規則寫進去。但有些偏好是個人的、是跨專案的，寫進某個專案的 CLAUDE.md 不太對。

Memory 系統就是為了解決這個問題。

它讓 Claude Code 把你的偏好、回饋、專案脈絡存成檔案，下次 session 自動載入。

---

📂 Memory 的運作方式

檔案式儲存

Memory 不是存在雲端，而是存成本機的 Markdown 檔案：

~/.claude/
└── projects/
    └── {專案路徑}/
        └── memory/
            ├── MEMORY.md          ← 索引檔
            ├── user_role.md       ← 使用者角色
            ├── feedback_testing.md ← 回饋記錄
            └── project_auth.md    ← 專案脈絡

每一條記憶就是一個 .md 檔案，你可以直接用文字編輯器打開來看、修改、刪除。完全透明，沒有黑箱。

記憶檔案的格式

每個記憶檔案有 YAML frontmatter + 內容：

---
name: 不要加 Co-Authored-By
description: commit message 中不要加入 Co-Authored-By 標記
type: feedback
---

commit 時不要加 Co-Authored-By 和 Generated with Claude Code。
使用者偏好乾淨的 commit message，只包含 issue 編號和改動描述。

**Why:** 使用者的團隊不希望在 git log 中看到 AI 標記。
**How to apply:** 所有 git commit 操作都適用。

MEMORY.md 索引檔

MEMORY.md 是記憶的「目錄」，列出所有記憶的摘要。Claude Code 啟動時會讀取這個索引，決定要載入哪些記憶。

- [不要加 Co-Authored-By](feedback_no_coauthor.md) — commit 不加 AI 標記
- [使用者是後端工程師](user_role.md) — 熟悉 PHP/MySQL，前端經驗較少
- [AppSystem 認證模組重構](project_auth.md) — 認證模組正在重構中

注意：MEMORY.md 超過 200 行會被截斷，所以每條記憶只用一行描述。

---

🔑 四種記憶類型

user（使用者）

關於你是誰、你的角色、你的知識背景。

---
name: 使用者角色
description: 後端工程師，熟悉 PHP/MySQL，正在學習前端
type: user
---

使用者是後端工程師，主要使用 PHP 7.4 和 MySQL 5.7。
對 Docker、多租戶架構有豐富經驗。
前端（React、Vue）經驗較少，解釋前端概念時用後端的類比會更容易理解。

用途：Claude 會根據你的背景調整解釋方式。對資深後端工程師，不需要解釋什麼是 JOIN；但如果你對前端不熟，React 的概念就需要多解釋。

feedback（回饋）

你對 Claude 的行為修正——什麼該做、什麼不該做。

---
name: 不要自動 push
description: git commit 後不要自動 push，讓使用者自己決定
type: feedback
---

commit 之後不要自動 push。使用者習慣先 review 一次再 push。

**Why:** 使用者曾經被自動 push 推到錯誤的 branch。
**How to apply:** 所有 git 操作結束後，告知完成但不要 push。

重點：不只記「什麼不要做」，也記「什麼做得好」。如果 Claude 某次的做法你覺得很好，也值得記下來，避免未來偏離。

project（專案）

關於目前工作的脈絡——誰在做什麼、為什麼、截止日期。

---
name: 認證模組重構中
description: AppSystem 的認證模組正在從 Session 遷移到 JWT，預計 2026-04-30 完成
type: project
---

認證模組正在從 Session-based 遷移到 JWT。

**Why:** 法務要求 Session token 的儲存方式需要符合新的合規標準。
**How to apply:** 認證相關的修改要考慮 JWT 遷移的方向，不要新增 Session 依賴。

注意：project 記憶容易過期。遷移完成後記得刪除或更新。

reference（參考）

外部資源的指引——在哪裡找什麼資訊。

---
name: Bug 追蹤在 Linear
description: 所有 bug 在 Linear 的 INGEST 專案追蹤
type: reference
---

Bug 追蹤使用 Linear，專案代號 "INGEST"。
如果使用者提到 ticket 編號，指的是 Linear 上的 issue。

---

⚙️ 怎麼使用 Memory

手動儲存：直接說「記住」

最直接的方式——告訴 Claude 記住某件事：

你：記住我偏好用 pnpm 而不是 npm
Claude：（建立記憶檔案，更新 MEMORY.md）
      已記住：偏好使用 pnpm。

你：記住這個專案的 staging 環境在 staging.example.com
Claude：（建立 project 類型的記憶）
      已記住：staging 環境位址。

手動刪除：說「忘記」

你：忘記之前說的 pnpm 偏好
Claude：（刪除對應的記憶檔案，更新 MEMORY.md）
      已刪除相關記憶。

自動儲存

Claude Code 也會自動偵測值得記住的事情：

觸發情境	記憶類型
你修正 Claude 的做法	feedback
你確認 Claude 的做法很好	feedback
你提到自己的角色或背景	user
你分享專案的重要脈絡	project

自動儲存比較保守——Claude 不會把每句話都記下來，只記「看起來會影響未來工作」的資訊。

---

📊 Memory vs CLAUDE.md：什麼時候用哪個？

這是最常被問到的問題。兩者互補，不是替代關係。

面向	CLAUDE.md	Memory
範圍	單一專案	個人（跨專案）或單一專案
格式	自由格式 Markdown	結構化（frontmatter + 分類型別）
版本控制	提交到 git，團隊共用	個人，不提交 git
編輯方式	直接編輯檔案或請 Claude 改	對話中說「記住」「忘記」
適合放什麼	專案規範、建置指令、架構說明	個人偏好、行為修正、工作脈絡

選擇原則：

團隊都該遵守的規則 → CLAUDE.md
只有你個人的偏好   → Memory（user / feedback）
專案當前的狀態     → Memory（project）
外部資源的指引     → Memory（reference）

實際搭配範例

CLAUDE.md：
  "commit message 格式為 issue-{編號} {描述}"

Memory（feedback）：
  "不要加 Co-Authored-By"

Memory（user）：
  "使用者是後端工程師，解釋前端概念時用後端類比"

Memory（project）：
  "認證模組正在重構，不要新增 Session 依賴"

CLAUDE.md 管「專案的規則」，Memory 管「你個人的規則」和「當前的狀態」。

---

💡 有效使用 Memory 的建議

1. 記憶要具體

❌ "記住我喜歡乾淨的程式碼"
✅ "記住我不要在函數開頭加空行，return 前也不要加空行"

太模糊的記憶沒有指導價值。

2. 記「為什麼」，不只記「什麼」

❌ "不要用 any 型別"
✅ "不要用 any 型別。原因：上次用 any 導致 runtime error，
    debug 花了兩小時才找到型別不符的問題"

記下「為什麼」讓 Claude 能判斷邊界情況——比如在 prototype 階段，any 也許是可以接受的。

3. 定期清理

Memory 沒有自動過期機制。Project 類型的記憶特別容易過期：

"認證模組正在重構" → 重構完成後，這條就該刪掉
"下週三之前不要合併 feature branch" → 過了就該刪掉

每個月花 5 分鐘看一下 MEMORY.md，刪掉過時的記憶。

4. 不要把所有東西都存進 Memory

每條記憶都會佔用 context window 空間。存太多反而會稀釋重要資訊。

不需要存的：

• 程式碼結構（Claude 自己讀就知道）
• git 歷史（git log 就能查）
• 除錯方案（修正已經在程式碼裡了）
• 已經寫在 CLAUDE.md 中的規則

---

⚠️ 注意事項

記憶可能過時

記憶記錄的是「寫入當下」的事實。如果專案後來改了，記憶沒更新，Claude 會照著舊的記憶工作。

Claude Code 的處理方式是：如果記憶和當前程式碼矛盾，以程式碼為準。但不是每次都能偵測到矛盾，所以定期清理仍然必要。

MEMORY.md 的 200 行限制

MEMORY.md 超過 200 行會被截斷。如果你的記憶很多，保持索引簡潔：

✅ - [不加 Co-Authored-By](feedback_no_coauthor.md) — commit 不加 AI 標記
❌ - [不加 Co-Authored-By](feedback_no_coauthor.md) — 使用者曾多次要求 commit message 中不要加入 Co-Authored-By 和 Generated with Claude Code 標記，原因是團隊不希望在 git log 中看到 AI 相關的標記

一行一條，不超過 150 字元。

和 Plan、Task 的區別

機制	時間範圍	用途
Memory	跨 session	長期偏好和知識
Plan	單次任務	複雜任務的執行計劃
Task	當前 session	工作進度追蹤

不要把 session 內的臨時資訊存成 Memory。Plan 和 Task 結束就消失，Memory 會一直留著。

---

🎉 結語

Memory 系統解決了一個很基本的問題：讓 Claude 記住你說過的話。

它不複雜——就是把你的偏好存成檔案，下次自動讀取。但這個簡單的機制帶來的體驗提升很明顯：你不需要每次開新 session 都重複「不要加 Co-Authored-By」「我是後端工程師」「認證模組在重構」。

和 CLAUDE.md 搭配使用的效果最好：

• CLAUDE.md 管「這個專案的規則」（團隊共用）
• Memory 管「我的偏好」和「當前狀態」（個人專用）

兩層加起來，Claude 每次開新 session 都帶著完整的上下文開始工作。

---

📎 相關文章：

• 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（上）
• 打造 AI 友善的專案文檔：CLAUDE.md 完整指南（中）
• CLAUDE.md 實戰模板集：五種專案類型的寫法
• Claude Code 自訂 Slash Commands：打造你的專屬 AI 工作流