wen aidev
Published on

Claude Code 記憶機制徹底解析：CLAUDE.md 與自動記憶實戰 (2026更新)

Table of Contents

在使用 Claude Code 開發一段時間後，你可能會發現它越來越懂你的專案習慣，或者有時候它又會突然「忘記」你之前千叮嚀萬交代的重要規則。

了解 Claude Code 的記憶機制 (Memory System) 是從「試用」跨入「專業生產力」的必經之路。到了 2026 年，Claude Code 的記憶機制已經演化出非常成熟的雙層架構，本文將帶你一次搞懂其中原理，以及如何避開大專案中常見的記憶體崩潰地雷。

雙層記憶架構：CLAUDE.md vs. Auto Memory

你可以把 Claude Code 的記憶想像成一個新進員工的腦袋。他需要一本「員工手冊」（固定不變的死規矩），同時他自己也會寫「工作筆記」（專案中學到的經驗）。

這兩者分別對應到 Claude Code 的兩大記憶引擎：

1. 專案規則 (CLAUDE.md)：絕對服從的憲法

CLAUDE.md 是一個純文字 Markdown 檔案，它的作用是強制注入上下文 (Context Injection)。每次你開啟對話，Claude 都會無條件先讀取這個檔案裡的內容。

這代表什麼？這代表你應該把最致命、最絕對不容許犯錯的規矩寫在這裡。

常見的使用情境：

  • 基礎編碼風格：(例如：請一律使用 TailwindCSS v4，不要寫 inline-style)。
  • 架構決策：(例如：我們使用 Next.js App Router，請不要使用 Pages Router 的寫法)。
  • 測試與提交流程：(例如：提交 PR 前一定要跑 yarn lint 並且通過)。

CLAUDE.md 的放置位置 (優先順序從高到低)：

  1. 目前工作目錄 (./CLAUDE.md 或 ./.claude/CLAUDE.md)
  2. 使用者全域目錄 (~/.claude/CLAUDE.md)
  3. 組織範圍佈署 (如 Windows 下的 C:\Program Files\ClaudeCode\CLAUDE.md)

越靠近當前目錄的設定會覆蓋較遠的設定，這對於 Monorepo (單體多專案庫) 來說非常方便。

2. 自動記憶 (Auto Memory)：AI 的私房筆記

相較於你要手寫的 CLAUDE.md，Auto Memory 是 Claude Code 自己在背景偷偷寫的筆記本。

當你在開發過程中，Claude 解決了一個棘手的 bug，或是搞懂了你們家複雜的 API 架構，它會把這些心得記錄下來。

它是怎麼運作的？

  • 筆記存放在你電腦的 ~/.claude/projects/<project>/memory/ 目錄下。
  • 裡面會有一個核心檔案叫做 MEMORY.md (摘要索引)，以及各種特定主題的檔案 (例如 debugging.md, api-conventions.md)。
  • 每次開啟新對話時，Claude Code 會自動載入 MEMORY.md 了解全局，如果對話涉及特定主題，它再去翻找對應的細節檔案。

2026 最新 CLAUDE.md 撰寫實戰與模組化

隨著專案變大，如果你把所有規定都塞進一個 .md 檔，很快就會變成災難。太長的指令不僅會吃掉你寶貴的 Context Window (上下文長度)，還會導致 Claude 的注意力渙散，開始忽略某些規則。

WARNING

黃金法則：CLAUDE.md 應盡量保持在 200 行以內。每一行都在消耗 token 與 AI 的注意力。

模組化技巧：使用 .claude/rules/ 與 @import

到了 2026 年，最推薦的做法是將規則拆分重組。

1. 使用 rules 目錄自動觸發

你可以建立一個 .claude/rules/ 目錄，把設定檔依照主題拆開：

your-project/
├── .claude/
│   ├── CLAUDE.md         # 最精簡的核心指令 (10行以內)
│   └── rules/
│       ├── code-style.md # 只有寫 Code 時才看的風格指南
│       ├── testing.md    # 只有寫 Test 時才看的規定
│       └── security.md   # 安全性規範

把檔案放在這裡的好處是，Claude 知道在遇到相關問題時再去查閱這些文件，而不是一開場就把幾千字塞進腦袋裡。

2. 強大且精準的 paths 範圍對焦

在 .claude/rules/ 裡面的 markdown 檔，你可以使用 YAML frontmatter 來設定生效路徑。這是大幅提升命中率的殺手級功能！

舉例來說，建立一個 .claude/rules/api-design.md：

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

# API 開發規則

- 所有的 API 端點都必須包含輸入驗證 (Input Validation)
- 發生錯誤時請統一回傳 { error: string, code: number } 格式

這代表：只有當 Claude Code 正在修改或讀取 src/api 底下的 TypeScript 檔案時，這些規矩才會生效。

3. @import 語法：跨檔案引用

有時候你希望讓 Claude 直接參考你寫好的開發流程設計書，不需要再複雜地複製貼上：

# 專案整體說明

請參考 @README 了解專案背景。

# Git 提交流程

請嚴格遵守 @docs/git-instructions.md 裡的規範。

致命地雷與疑難排解 (Troubleshooting)

記憶系統雖然強大，但如果不定期修剪，就像瀏覽器開了幾百個分頁一樣會當機。特別是在 2026 年初的某些版本 (如 2.1.72)，曾回報過嚴重的 Memory Leak (記憶體洩漏)。

遇到 Claude「失憶」或「效能低落」怎麼辦？

  1. 我不知道自駕累積了什麼莫名其妙的規則？ 在終端機輸入：

    /memory

    你可以直接叫出互動介面，查看、修改甚至刪除 Claude 自己寫錯或過時的 Auto Memory 筆記。

  2. 我的 CLAUDE.md 太肥了，Claude 開始不聽話！ 這是最常見的問題。解法就是：改寫指令，注重動詞與結果。

    • ❌ 錯誤寫法：「請確保程式碼格式正確且漂亮」 (太抽象)
    • ✅ 正確寫法：「請使用 2 格空白縮排」
    • ❌ 錯誤寫法：「測試一下有沒有壞掉」
    • ✅ 正確寫法：「提交前執行 npm test」

  3. 越跑越慢，似乎指令在 /compact (壓縮記憶) 後就遺失了？ /compact 會壓縮對話紀錄，但不會影響到你的 CLAUDE.md 和自動記憶 MEMORY.md。如果你覺得規則沒生效：

    • 確認你的路徑設定是否正確。
    • 確認你的 CLAUDE.md 是不是超過了 200 行，導致前面的規則被擠出了關注點。
    • 定期手動進 /memory 砍掉真的沒用到的陳舊筆記。

總結

善用 CLAUDE.md (固定法規) 與 Auto Memory (經驗累積本)，是解鎖 AI 結對程式設計 (Pair Programming) 全速率的關鍵。把大原則留在根目錄，把細部規則拆進 .claude/rules/ 並綁定 paths，你的 Claude Code 就再也不會忘記你們家的開發鐵則了！

👉 下一步： 了解完底層規則運作後，如果你想實際操作看看有哪些隱藏好用的指令，可以前往 進階指令 2026 首發搶先看。

留言討論