第四章：記憶與治理架構

Chapter 4: Memory & Governance Architecture

4.0 導讀

本章說明 Claude Code 系統中「指令如何生效」與「資訊該寫在哪裡」兩件事。

對技術人員：這是你維護任何 CLAUDE.md 或記憶檔案前必須理解的分工地圖。對管理層：這是我們用最少常駐成本換取最大上下文品質的設計邏輯。

核心問題只有三個：

指令從哪裡來、優先順序是什麼？
一筆資訊該存在哪一層？
怎麼確保不重複、不過期、不浪費 token？

4.1 CLAUDE.md 四層指令階層

Claude Code 的行為由一組分層的 CLAUDE.md 檔案控制。每一層在特定範圍內自動生效，越深層越具體，但不覆寫上層規則 -- 它們是疊加（additive）關係。

4.1.1 階層總覽

Layer 1  ~/.claude/CLAUDE.md          ← User-level：全域常駐
Layer 2  ~/CLAUDE.md                  ← Workspace：整個工作空間
Layer 3  ~/.claude/projects/CLAUDE.md ← Subtree：projects/ 子樹
Layer 4  ~/.claude/projects/{name}/CLAUDE.md ← Project：單一專案

4.1.2 各層詳述

Layer 1：User-Level（`~/.claude/CLAUDE.md`）

項目	說明
生效範圍	所有 Claude Code session，無論在哪個目錄工作
內容定位	系統憲法 -- 最小規則集與權威文件指向
典型內容	權威來源指向（`REGISTRY.md`、`memory.md`、`roadmap.md`）、原生優先規則、操作預設
維護者	系統管理員（人工）
設計原則	極簡、單語言、只放指向不放細節；減少每次 session 的固定 token 開銷

為什麼這樣設計：這一層每次 session 都會被載入，因此必須嚴格控制行數。它只回答「規則在哪裡」，不回答「規則是什麼」。

Layer 2：Workspace（`~/CLAUDE.md`）

項目	說明
生效範圍	工作目錄位於 `/home/ubuntu` 及其子目錄時
內容定位	工作空間的操作契約
典型內容	通訊語言（繁體中文）、原生階層使用規範、single-owner 模型、canonical 文件清單
維護者	系統管理員（人工），由 repo-tracked source 提供，SessionStart hook 自動校正
設計原則	定義「在這台機器上工作」的通用規矩；不放專案細節

為什麼這樣設計：一台 VPS 可能跑多個專案，但操作慣例（語言、協作模型、安全邊界）應該一致。這一層確保所有專案共享同一套操作契約。

Layer 3：Subtree（`~/.claude/projects/CLAUDE.md`）

項目	說明
生效範圍	工作目錄位於 `~/.claude/projects/` 子樹時
內容定位	所有專案共通的結構與邊界規範
典型內容	專案標準結構（`CONTEXT.md`、`DECISIONS.md`、`memory/MEMORY.md`）、記錄邊界、生命週期規則
維護者	系統管理員（人工）
設計原則	保證每個專案有一致的骨架，但不干預專案內部決策

為什麼這樣設計：當專案數量增加，缺乏統一結構會導致混亂。這一層是「專案該長什麼樣」的規範，而不是「專案該做什麼」。

Layer 4：Project（`~/.claude/projects/{name}/CLAUDE.md`）

項目	說明
生效範圍	僅在該專案目錄內工作時
內容定位	專案特定的上下文與規則
典型內容	專案背景、活動索引、專案特殊規則
維護者	專案負責人（人工）+ claude-mem runtime artifact（自動注入）
設計原則	可以放專案獨有的指令，但優先考慮是否能被上層或 canonical doc 吸收

為什麼這樣設計：個別專案可能有特殊需求（例如特定的 API 慣例、命名規範），但使用前應確認這些需求是否真的是專案獨有的。避免在每個專案都重複定義相同規則。

4.1.3 階層運作原則

1. 疊加不覆寫：各層指令是累積的，下層補充上層，不取代上層
2. 最小常駐：越上層的檔案越精簡，因為它們的載入頻率最高
3. 具體下沉：通用規則放上層，專案特定規則放下層
4. 能吸收就不新增：path-scoped rules 是最後手段，優先使用既有 canonical doc

4.2 記憶架構七層分工

系統的「記憶」分散在七個層次。每一層有明確的用途、維護者與邊界。核心原則是：一筆資訊只存在一個地方，其他地方只做指向。

4.2.1 分層總覽

層號	名稱	路徑	用途	維護方式	存什麼	不存什麼
L0	git	repo history	變更事實來源	自動 + 人工 commit	實際 diff、commit message	--
L0.5	logs/	`~/.claude/logs/`	事件日誌	人工/腳本追加	skill run、audit、cron 檢查結果	長篇設計脈絡
L0.8	project decisions	`projects/{name}/DECISIONS.md`	專案決策記錄	人工維護	決策、取捨、已確認規則	里程碑摘要
L0.9	project memory	`projects/{name}/memory/MEMORY.md`	專案里程碑	人工維護	里程碑摘要、高層脈絡	diff 重抄、事件日誌
L1	native memory	`CLAUDE.md` 階層 + built-in memory	持久指令與自動學習	原生機制	指令、路徑規則、自動累積的工作記憶	可由 canonical doc 吸收的內容
L1.5	claude-mem	MCP plugin	跨 session 觀察檢索	全自動	bugfix/feature/discovery/decision 索引	權威記錄
L2	global memory	`~/.claude/memory/`	長期原則與偏好	人工整理	經驗證有效的規則、反模式、文化偏好	專案特定細節

4.2.2 各層詳述

L0：git -- 變更事實來源

git 是唯一的檔案變更事實來源。任何關於「什麼時候改了什麼檔案」的問題，答案都在 git history 裡，不在別處。

存：每一次 commit 的完整 diff、commit message、作者、時間
不存：解釋「為什麼」做這個改動（那是 decisions 或 commit message 的工作）
原則：不在 MEMORY.md 手寫會與 git 重複且可能不一致的檔案清單

L0.5：logs/ -- 事件日誌

~/.claude/logs/ 記錄系統運行事件，包括 skill 執行結果、定期 audit、cron 檢查。

格式：月份 JSONL（2026-03.jsonl）+ 獨立 audit 報告
存：事件時間戳、執行結果摘要、指向詳細報告的路徑
不存：設計討論、架構決策、里程碑敘述
原則：若已有報告檔案，logs 只需指向報告位置，不重抄內容

L0.8：project decisions -- 專案決策

每個專案的 DECISIONS.md 記錄該專案內部的技術與業務決策。

存：決策內容、取捨分析、已確認的專案規則
不存：執行細節、程式碼片段、里程碑時間線
原則：決策一旦確認就寫入；若後續被推翻，標記為棄用並說明原因

L0.9：project memory -- 專案里程碑

每個專案的 memory/MEMORY.md 記錄高層脈絡與重要里程碑。

存：里程碑摘要（日期 + 一兩句話）、重要結果、專案狀態轉換
不存：diff 逐行摘要、日常 typo 修正記錄、可從 git log 查到的細節
原則：小修補除非影響架構或流程，不必記錄

L1：Claude Code native memory -- 第一方記憶

Claude Code 原生的指令階層（見 4.1）加上 built-in auto memory 機制。

存：持久指令、路徑規則、系統自動累積的工作模式記憶
不存：可由 DECISIONS.md、MEMORY.md 或其他 canonical doc 更乾淨承載的內容
原則：這是最高優先的記憶機制。只有原生能力不足且有充分證據時，才考慮自建延伸層

L1.5：claude-mem -- 自動觀察層

MCP plugin，SessionStart hook 自動注入最近 25 筆觀察索引至 session context。

存：四類事件索引（bugfix / feature / discovery / decision）的標題與 token 估計
不存：完整的事件內容（需透過 MCP 查詢取得）
定位：補充型檢索工具，不是權威記錄來源
注意：此 plugin 會在讀寫過的目錄自動注入 <claude-mem-context> 至子目錄 CLAUDE.md。這是 runtime artifact，不納入架構設計，不應進入 canonical git tracking

L2：global memory -- 長期原則

~/.claude/memory/ 目錄下的人工維護檔案，記錄跨專案有效的原則與偏好。

檔案：learnings.md（學習心得）、dont-do.md（反模式）、culture.md（文化偏好）、preferences.md（操作偏好）
存：經驗證仍有效的通用規則、明確的反模式警告
不存：專案特定的決策或里程碑
維護：人工整理，按需讀取（不自動注入），各檔上限 200 行
原則：寧可少而精確，不要多而過期

4.2.3 已退役層：agent-memory/

~/.claude/agent-memory/ 是早期的自建 Agent 跨 session 記憶實驗，已退役。保留目錄僅作歷史參考，不再新增內容，不應被任何 workflow 依賴。重新啟用的前提是：原生能力確實無法覆蓋，且能證明自建層有獨特收益。

4.3 治理原則

4.3.1 Single Source of Truth（唯一事實來源）

一筆資訊只存在一個權威位置。
其他位置只做指向，不做複製。

問題	權威來源
某個檔案什麼時候被誰改了？	git history
某次 skill 執行的結果？	logs/
為什麼選了方案 A 而不是方案 B？	project DECISIONS.md
專案目前走到哪裡了？	project memory/MEMORY.md
系統應該怎麼運作？	CLAUDE.md 階層
跨專案的通用教訓？	global memory/

違反這個原則的典型症狀：在 MEMORY.md 裡手寫一份檔案清單，然後它與 git 實際狀態不一致。

4.3.2 不重複記錄

如果 git diff 已經記錄了變更細節，MEMORY.md 不需要重抄。
如果 logs/ 已經記錄了事件，DECISIONS.md 不需要重述。
如果 CLAUDE.md 已經定義了規則，memory/ 不需要再寫一遍。

判斷規則：如果刪除這筆記錄，能從另一個來源無損復原嗎？ 如果能，它就是重複的。

4.3.3 最小常駐 Token

每次 session 啟動時，Claude Code 會自動載入所有生效的 CLAUDE.md 層。這些是「固定成本」。

設計策略：

Layer 1（user-level）：極簡指向，不放細節 -- 因為每次都載入
Layer 2（workspace）：操作契約，控制在 30 行以內
Layer 3（subtree）：結構規範，控制在 20 行以內
Layer 4（project）：可以稍長，因為只在該專案內載入
global memory/：按需讀取，不自動注入 -- 這是刻意的設計決策
claude-mem 注入：控制在 25 筆索引，每筆只有標題與 token 估計

管理層視角：token 是直接成本。常駐指令越精簡，每次 session 可用於實際工作的 context window 就越大。這不是技術潔癖，是資源效率。

4.4 專案生命週期管理

每個專案從建立到結束，經歷四個階段。記憶治理在每個階段有不同的關注點。

4.4.1 建立（Create）

動作：
  - 建立專案目錄 ~/.claude/projects/{name}/
  - 建立 CONTEXT.md（專案背景與目標）
  - 建立 DECISIONS.md（空模板）
  - 建立 memory/MEMORY.md（空模板）
  - 可選：CHANGELOG.md

治理重點：
  - 確認專案結構符合 subtree 規範
  - CONTEXT.md 清楚定義專案邊界，避免後續 scope creep

4.4.2 進行（Active）

動作：
  - 日常工作產生 git commits
  - 重要決策寫入 DECISIONS.md
  - 里程碑完成時更新 MEMORY.md
  - 事件記錄寫入 logs/

治理重點：
  - 定期檢查是否有資訊放錯層（常見：在 MEMORY.md 重抄 diff）
  - 確認 DECISIONS.md 有記錄關鍵取捨，而不只是結果
  - claude-mem 自動注入的 runtime artifact 不進 git

4.4.3 歸檔（Archive）

動作：
  - 更新 CONTEXT.md 標記專案狀態為完成或暫停
  - 確認 MEMORY.md 有最終里程碑摘要
  - 確認 DECISIONS.md 記錄了所有重要決策

治理重點：
  - 歸檔的專案不應繼續產生新記錄
  - 目錄保留但不再活躍維護

4.4.4 萃取教訓（Extract & Close）

動作（三選一）：
  a. 刪除：專案已無參考價值
  b. 封存：保留目錄作歷史參考，不再維護
  c. 萃取：將跨專案有效的教訓寫入 global memory/

治理重點：
  - 萃取時只提取「經驗證仍有效的通用規則」，不搬專案特定細節
  - 萃取後的教訓需符合 global memory 各檔 200 行上限
  - 明確宣告專案生命週期結束，避免殭屍專案

4.5 記憶分層架構圖

                    ┌─────────────────────────────────────────┐
                    │          Session Context Window          │
                    │    （每次對話可用的 token 總預算）         │
                    └────────────────┬────────────────────────┘
                                     │
              ┌──────────────────────┼──────────────────────┐
              │                      │                      │
              ▼                      ▼                      ▼
   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
   │  自動載入區       │   │  自動注入區       │   │  按需讀取區       │
   │  (Fixed Cost)    │   │  (Plugin Cost)   │   │  (On-Demand)    │
   ├─────────────────┤   ├─────────────────┤   ├─────────────────┤
   │ L1 CLAUDE.md    │   │ L1.5 claude-mem │   │ L2 global       │
   │   User-level    │   │   25 筆觀察索引  │   │   memory/       │
   │   Workspace     │   │   ~500 tokens   │   │   learnings     │
   │   Subtree       │   │                 │   │   dont-do       │
   │   Project       │   │                 │   │   culture       │
   │                 │   │                 │   │   preferences   │
   └─────────────────┘   └─────────────────┘   └─────────────────┘

              ┌──────────────────────────────────────────────┐
              │              持久化儲存區                      │
              │         （不佔 session token）                 │
              ├──────────────────────────────────────────────┤
              │                                              │
              │  L0    git           變更事實（diff/history） │
              │  L0.5  logs/         事件日誌（JSONL/audit）  │
              │  L0.8  DECISIONS.md  專案決策與取捨            │
              │  L0.9  MEMORY.md     專案里程碑摘要            │
              │                                              │
              │  ---- 已退役 ----                             │
              │  L3    agent-memory/ （歷史參考，不再使用）     │
              │                                              │
              └──────────────────────────────────────────────┘

圖解說明

上半部是每次 session 會進入 context window 的內容，直接影響 token 成本：

自動載入區：CLAUDE.md 四層階層，每次 session 必定載入。這是固定成本，所以必須極簡。
自動注入區：claude-mem plugin 透過 SessionStart hook 注入的觀察索引。成本可控（約 500 tokens），但內容是 runtime artifact，不是設計的一部分。
按需讀取區：global memory 檔案，只在 agent 主動讀取時才佔用 token。這是刻意設計 -- 不是所有長期知識都需要每次載入。

下半部是持久化儲存，不佔用 session token，但隨時可以被查詢：

git 記錄所有變更事實
logs 記錄所有事件
DECISIONS.md 記錄所有決策
MEMORY.md 記錄所有里程碑

兩個區域之間的關係是：上半部決定 agent 在對話中「知道什麼」，下半部決定系統「記住什麼」。 好的治理確保需要知道的會被載入，需要記住的會被持久化，而兩者之間沒有冗餘。

4.6 多 AI 協作下的記憶治理

當多個 AI（Claude Code、Codex 等）在同一系統工作時，記憶治理需要額外的協調機制。

共享底座（Shared Substrate）

以下四層是所有 AI 共同依賴、但不應各自重造的系統真相：

git：變更事實與提交邊界
canonical docs：REGISTRY.md / memory.md / roadmap.md
logs/：事件與 telemetry
eval artifacts：baseline / candidate / scorecard

Adapter 模型

每個 AI 都視為 adapter，不是各自建立一套 system-of-record。各自的 runtime memory、plugin cache、session context 都是 session-local state，不得視為權威來源。

Single-Owner 規則

一個任務只能有一個 primary executor。owner 依 substrate proximity 決定：誰最貼近該任務實際運作的 runtime / tool / file substrate，就由誰主控。非 owner 的 AI 僅作為 reviewer / challenger / specialist，透過 git、canonical docs、handoff、logs 進行交接。

4.7 本章小結

設計決策	理由
四層 CLAUDE.md 階層	平衡通用性與專案特殊性，同時控制常駐 token
七層記憶分工	每種資訊有明確的家，避免重複與不一致
git 為唯一變更事實來源	消除人工摘要與實際狀態不一致的風險
global memory 按需讀取	減少固定 token 成本，只在需要時載入
claude-mem 為補充層	提供跨 session 連續性，但不取代權威記錄
agent-memory 已退役	原生能力已可覆蓋，自建層缺乏維護收益
專案生命週期四階段	確保專案不會變成殭屍，教訓能被萃取

權威參考文件：~/.claude/docs/memory.md -- 記憶分工的 canonical source of truth。本章是其架構說明，非取代。

建立日期：2026-03-10 權威來源：~/.claude/docs/memory.md、~/.claude/CLAUDE.md、~/CLAUDE.md、~/.claude/projects/CLAUDE.md