先說結論

你如何維護你的 CLAUDE.md？你有沒有遇到這兩個問題：

第一，隨著專案長大，單一檔案塞滿規則，AI 的 Context Window 被廢話稀釋
第二，你根本不知道 Claude 到底在哪裡鬼打牆，你只有「感覺它怪怪的」

這篇文章分享我整理 CLAUDE.md 的方法，這套方法有三層：

  1. 階層式 CLAUDE.md — 保護 Context，讓 AI 在對的時間看到對的規則
  2. 自訂 skill /Lesson — 任務完成後回顧這段對話，提取經驗寫入 CLAUDE.md
  3. 自訂 skill /project-insights — 自動審計，Claude 回頭看自己的表現，直接開處方

三層疊起來會形成一個 PDCA 循環。你的 CLAUDE.md 會自己長出該有的規則，Claude 的行為也會跟著變好

PS. 就跟封面圖一樣，儲思盆就是鄧不利多的 CLAUDE.md

第一層：階層式 CLAUDE.md

我之前在「為什麼你的 AI 比較笨？」那場分享裡提過，AI 犯錯有三個根源：錯誤的資訊、遺漏的資訊、雜訊

階層式 CLAUDE.md 主要解決的就是「雜訊」

你在寫前端的時候，後端的 API 格式規範對 Claude 來說就是雜訊。它佔了 Context Window 的空間，卻對當前任務毫無幫助，反而可能讓 Claude 分心。寫越多，Claude 反而越笨

如果你的 CLAUDE.md 塞滿了所有規則，前端的 Component 寫法、後端的 API 格式、部署流程、命名規範全部攪在一起，AI 的注意力會被稀釋

正確的做法是分層：

project/
├── CLAUDE.md              ← 全域規則（Global Rules）
├── frontend/
│   └── CLAUDE.md          ← 前端專屬規範
└── backend/
    └── CLAUDE.md          ← 後端專屬規範

為什麼這樣做有效

Claude Code 會自動載入你當前工作目錄的 CLAUDE.md。當你在 frontend/ 底下工作，它會從當前目錄往上遞迴，載入到根目錄的所有 CLAUDE.md 檔案

也就是說這樣他只會載入專案根目錄的 CLAUDE.md 加上 frontend/CLAUDE.md，後端的 CLAUDE.md 不會被載入，不會佔用 Context Window

保護你的 Context，AI 只在對的時間看到對的規則

所以每一層的 CLAUDE.md 該放什麼

根目錄 CLAUDE.md：只放每次對話都需要的東西

  • 核心開發哲學
  • 全域命名規範
  • Git commit 慣例
  • 專案整體架構概述

子目錄 CLAUDE.md：放該領域的專屬規則

  • frontend/CLAUDE.md：Component 寫法、狀態管理慣例、UI 框架注意事項
  • backend/CLAUDE.md：API 格式、資料庫操作慣例、第三方服務整合

原則很簡單：某條規則只在前端會用到，就不該放在根目錄浪費全域的 Context

動態載入：CLAUDE.md 當索引用

有些東西真的太大了。教學文件、API 速查表、完整的框架指南，直接塞進 CLAUDE.md 會爆

更好的做法是把 CLAUDE.md 當成索引：只列出「去哪裡找」，Claude 需要的時候再動態載入

這樣 CLAUDE.md 始終保持精簡，但 Claude 又不會在需要的時候找不到資訊

第二層：/Lesson

有了架構，接下來的問題是：Claude 鬼打牆之後，那段經驗怎麼留下來

即便有了階層式架構，Claude 在協作中仍然會出現反覆修不好同一個 Bug、執著於錯誤的 API 用法、或是溝通出現斷層的狀況。你花了力氣把它導正、最終完成任務了，但如果什麼都不做，下次遇到同樣的問題它還是會再犯一次

/Lesson 是我自己做的一個 Custom Command。在任務完成之後，讓 Claude 回頭 review 這段對話

它做兩件事：

  1. 回顧對話：強迫 Claude 重新看一遍剛才那段鬼打牆的過程，分析哪裡走錯、為什麼最後能修正
  2. 提取經驗：把學到的教訓和正確做法，寫入對應層級的 CLAUDE.md

關鍵是「寫入對應層級」。如果是通用的教訓（比如「收到明確指令就直接執行」），寫根目錄。如果是某個框架的 API 踩坑寫子目錄。階層式架構在這裡發揮作用

不過人難免會懶惰或遺忘

你不可能每次任務結束都記得下 /Lesson，有些模式要累積幾十次才看得出來

所以才需要接下來第三層的 /project-insights 當最後補漏的防線

簡單說：

  • /Lesson 處理「單次 session」的經驗，精準但依賴人記得去做
  • /project-insights 處理「跨所有 session」的趨勢，全面但有延遲

先備知識：Claude Code 在你電腦上偷偷存了什麼

Claude Code 其實默默存了不少東西

對話紀錄（JSONL）

~/.claude/projects/{encoded-path}/{session-id}.jsonl

你跟 Claude 講的每句話、Claude 的每個回覆、用了什麼工具、花了多少 token，全部存在這裡

我最新的一個專案，44 天下來存了 260 個 session，整個資料夾超過 600MB，最大的一個 session 就 54MB

索引（sessions-index.json）

~/.claude/projects/{encoded-path}/sessions-index.json

Claude Code 幫大約 70% 的 session 整理好了基本資料：第一句話講什麼、摘要、訊息數量

有了這個，很多 session 不用打開 JSONL 就能知道大概在幹嘛

不過光有原始資料還不夠。你需要一個工具幫你分析這些東西，這就是第三層要做的事

第三層：/project-insights

先聊官方的 /insights

最近 Claude Code 出了一個新功能，打一個指令 /insights，會跑出一份自動分析的 HTML 報告

很屌，它會回頭翻你過去 30 天的對話紀錄，分析你用了哪些工具、哪裡卡關、session 的成功率多少

等於是讓 AI 回頭看自己的工作表現

/insights 幫你標註了什麼：Facets

/insights 它還會回頭看每個 session，建立一份叫 Facet 的後設分析，存在這裡：

~/.claude/usage-data/facets/{session-id}.json

每個 Facet 會標註：

Facet 欄位白話意思範例
goal_categories這個 session 在做什麼bug_fix、code_migration
outcome結果如何fully_achieved、not_achieved
friction_counts有什麼摩擦/卡關wrong_approach、buggy_code
claude_helpfulnessClaude 有多幫忙very_helpful、essential
session_type工作模式iterative_refinement、single_task

這些 Facet 就是讓 CLAUDE.md 從「憑感覺」變成「靠數據」的原料

不過 /insights 有兩個問題

看完報告之後，我覺得少了點什麼

第一，它分析的是所有專案。我手上同時有三個大專案，幾十個小專案在跑，報告把所有數據攪在一起，看到「wrong_approach 出現 20 次」，我不知道這是哪個專案的分析

第二，同樣的，你不知道要改哪個專案的 CLAUDE.md，你知道有哪些問題，但沒辦法針對那個專案去優化 CLAUDE.md

我想要的是：打一個指令，就能給我這個專案的 CLAUDE.md 哪裡修正建議，然後同意 -> 修改

所以我自己做了一個

/project-insights 做三件事：

  1. 只看當前專案 — 你在哪個專案目錄下跑，就只分析那個專案的紀錄
  2. 重用 /insights 已經分析過的資料 — 不重複花錢買 token
  3. 產出 CLAUDE.md 改進建議 — 不只告訴你哪裡痛，還直接開處方

技術上就兩個檔案：

~/.claude/skills/project-insights/
├── SKILL.md            # 告訴 Claude 怎麼分析、報告格式長怎樣
└── scripts/
    └── extract.py      # Python 腳本，負責取出對話紀錄

放在 ~/.claude/skills/ 底下，任何專案都能用

為什麼需要 Python 腳本

幾百 MB 的 JSONL，不能直接丟給 Claude 讀

一個 session 就可能 50MB 以上，讀幾個最大的 session 就塞滿 Context Window 了。所以需要一個腳本先濃縮：掃完所有檔案，把統計數字彙總成一份 100KB 的 JSON，再交給 Claude 分析

Python 串流處理 260 個 session，3.6 秒搞定

腳本做的事：

  1. 接收專案路徑，找到對應的 session 資料夾
  2. 先讀索引拿到基本 metadata（70% 不用解析 JSONL）
  3. 串流掃描每個 JSONL：訊息數、工具使用次數、token 消耗、錯誤次數、模型分佈
  4. 去比對哪些 session 已經有 Facet 分析
  5. 挑出 10 個「最值得 Claude 深入看」的未分析 session
  6. 全部彙總成 JSON 輸出

那 10 個 session 怎麼挑？不是隨機的：

  • 最多訊息的 3 個，對話最長的通常最複雜
  • 最多錯誤的 2 個，卡最久的
  • 最新的 3 個，反映最近的使用習慣
  • 最耗 token 的 2 個，成本最高的

報告長什麼樣

SKILL.md 裡定義了七個分析區塊，Claude 會按順序跑：

1. 概覽

基本統計：幾個 session、時間範圍、token 花了多少、Facet 覆蓋率多少

2. 工作內容分析

你最常叫 Claude 做什麼？寫程式？debug？寫文件？從 Facet 的 goal_categories 統計出來

3. 工具使用模式

哪些工具用最多、比例正不正常

從我自己的數據看：

Bash:  6,128 次
Read:  5,560 次
Edit:  3,942 次
Grep:  1,026 次
Glob:    780 次

Bash 比 Read 多。照 Claude Code 的最佳實踐，讀檔案應該用 Read 而不是 Bash，這就暗示我的 CLAUDE.md 可能要加強「優先用專用工具」的規範。事實上我後來確實加了

4. 摩擦點分析

這是我覺得最有價值的部分

buggy_code:           33 次  ← 產出的程式碼有 bug
wrong_approach:       24 次  ← Claude 選錯方向
misunderstood_request: 9 次  ← 誤解我要幹嘛
user_rejected_action:  8 次  ← 我否決了 Claude 的操作
excessive_changes:     3 次  ← 改太多，超出我要求的範圍

buggy_code 排第一我是有點意外的。Claude 寫的程式碼最常出 bug 的地方是第三方 API 的用法，比如 shadcn UI 的 Checkbox 用了錯的 prop 名稱、lifecycle hook 的行為跟文件寫的不一樣。這種東西靠 Claude 自己是很難避免的，但你可以把踩過的坑寫進 CLAUDE.md，下次就不會再犯

wrong_approach 排第二，主要是 Claude 不熟悉專案慣例，用了 raw fetch 而不是專案封裝的 $fetch、該直接改程式碼的時候跑去寫計畫文件。靠加強 CLAUDE.md 的架構說明就能改善很多

5. Session 結果分佈

fully_achieved:    94 次 (66%)
mostly_achieved:   26 次 (18%)
partially_achieved: 18 次 (13%)
not_achieved:        4 次  (3%)

84%「大部分完成」以上，比我想像中好。但那 16% 是什麼狀況？報告會幫你拉出失敗案例的共同模式。我的案例裡，not_achieved 的 4 個 session 幾乎都是同一個原因：Claude 花太多時間在規劃，我等不及就中斷了

6. 重複模式

掃所有 session 的第一句話跟摘要，看有沒有一直在做重複的事。如果有，也許該寫成自動化或另一個 Skill

7. CLAUDE.md 改進建議

整份報告的重點。前面六個區塊分析完，Claude 會整理出具體建議，標註類型和優先級：

  • [新增規範] — wrong_approach 太多 → CLAUDE.md 要加強架構說明
  • [修改規範] — 既有規範沒被遵守 → 改寫得更明確
  • [新增知識] — 同樣的問題反覆出現 → 加入常見陷阱
  • [效率提升] — 重複任務太多 → 建議自動化

每條建議都可以直接貼進 CLAUDE.md

覆蓋率的坑：/insights 要多跑幾次

這裡有個重要的細節

/insights 每次最多只處理 50 個 Facet，而且是全域的（跨所有專案一起算）。如果你跟我一樣有好幾個專案、幾百個 session，跑一次根本不夠

我自己親身經歷：一開始只跑了一次 /insights，254 個有意義的 session 裡只有 27 個有 Facet。覆蓋率 11%，報告裡的摩擦點分析基本上就是抽樣調查

後來我連續跑了好幾次 /insights，每次它就默默多處理 50 個 session，覆蓋率從 11% → 26% → 45% → 最後到 56%（143 個 Facet）

數據量差了 5 倍，分析結果也完全不同。摩擦點的排名變了，成功率的數字也更準確了

所以如果你認真想用這個工具，花個十分鐘多跑幾次 /insights 是值得的。它會自動跳過已經有 Facet 的 session，繼續處理下一批

實際跑出來的真實數字

拿我其中一個開發中的專案來說：

指標值
專案期間44 天
Session 總數260
使用者訊息22,000+
助理訊息16,000+
工具呼叫21,000+
錯誤總數600+
摩擦點82 次（跨 143 個已分析 session）

兩萬多則訊息，寫到這裡我都懷疑我跟 Claude 講的話比跟真人多了

跑了之後我真的改了什麼

光看報告不改東西等於白跑，所以我直接舉三個實際改了 CLAUDE.md 的例子

1. Bash > Read → 加了「優先使用專用工具」規範

報告的工具使用分析顯示 Bash 比 Read 多（6,128 vs 5,560），照 Claude Code 的最佳實踐，讀檔案應該用 Read 不是 cat，搜文字應該用 Grep 不是 grep

我後來在 CLAUDE.md 加了一張對照表，明確規定哪些操作用哪個工具。加了之後 Claude 真的比較少亂用 Bash 了

2. wrong_approach 太多 → 加了「直接執行不要產計畫」規範

24 次 wrong_approach 裡面有不少是 Claude 收到明確指令後還在那邊寫計畫文件，我等不及就直接中斷。最誇張的是有一次我說「fix all 15 findings」，Claude 寫了一份修正計畫給我看——拜託我都告訴你要修了，修就對了

所以我加了一條：「收到明確指令時直接執行，不要先產出計畫文件」

3. buggy_code 最多 → 加了第三方 API 速查表

33 次 buggy_code 裡面很大一部分是第三方 API 用法搞錯。shadcn-vue 的 Checkbox prop 用了舊版語法、Strapi 的 lifecycle hook 行為跟預期不同

這種錯 Claude 不會自己知道，但你寫進 CLAUDE.md 後它就不會再犯。等於是幫 Claude 建了一本專案專屬的 cheat sheet

跑起來之後的循環

這三層疊起來會形成一個循環：

  +-----------+      自動記錄       +---------------+
  |           | -----------------> |               |
  |  跟 Claude |    JSONL 對話紀錄   | /insights     |
  |  協作開發   |                    |  產生 Facet   |
  |           |                    |  (多跑幾次)    |
  +-----------+                    +-------+-------+
       ^                                   |
       |                                   v
  +-----------+                    +---------------+
  |           |     改進建議        |               |
  |  Claude   | <----------------- | /project-     |
  |  行為變好  |    寫入對應層級     |  insights     |
  |           |                    |  專案報告      |
  +-----------+                    +---------------+
       ^                                   |
       |          +---------------+        |
       +--------- |  更新階層式    | <------+
                  |  CLAUDE.md    |
                  +---------------+
                        ^
                        |
                  +---------------+
                  |  /Lesson      |
                  |  事後回顧      |
                  +---------------+

用 PDCA 的語言來說：

  1. Plan（載入）：Claude 讀取最新的階層式 CLAUDE.md，帶著上一輪的改進開始工作
  2. Do（協作）：專注開發，任務完成後用 /Lesson 回顧對話、提取經驗寫入 CLAUDE.md
  3. Check（審計）：定期跑 /project-insights，讓 Claude 幫你回顧歷史數據，找出你沒注意到的模式
  4. Act（更新）：根據報告建議，把規則分流寫入階層式的 CLAUDE.md。通用問題寫根目錄，特定技術問題寫子目錄

不再是憑感覺維護 CLAUDE.md。有數據，有根據

每次分析都能找到新的改進點，每次改進都會反映在下一輪的分析結果裡

/Lesson 像每次看完診後寫的病歷記錄，/project-insights 像定期健檢報告，階層式 CLAUDE.md 是整本病歷。搭在一起用，Claude 就不會一直犯同樣的毛病

想自己搞一個？

你需要

  • Claude Code（支援 Skills 的版本）
  • Python 3.8+
  • 用 Claude Code 一段時間，有 session 紀錄

三步驟

# 1. 建目錄
mkdir -p ~/.claude/skills/project-insights/scripts

# 2. 把 SKILL.md 和 extract.py 放進去（原始碼附在文末）

# 3. 給執行權限
chmod +x ~/.claude/skills/project-insights/scripts/extract.py

然後在任何專案目錄打 /project-insights 就好了

階層式 CLAUDE.md 的建立

不需要任何工具，就是在子目錄建立 CLAUDE.md 檔案：

# 在既有專案中新增子目錄規範
touch frontend/CLAUDE.md
touch backend/CLAUDE.md

然後把根目錄 CLAUDE.md 裡「只在特定目錄有用」的規則搬到對應的子目錄就好

/Lesson 的建立

這是 Claude Code 的 Custom Command，在專案根目錄建立 .claude/commands/lesson.md，裡面寫好你希望 Claude 在收到 /Lesson 時怎麼分析當前對話、怎麼把結論寫進 CLAUDE.md

結尾

寫這篇的時候我去看了一下電腦裡的 .claude 資料夾有 2 GB

WoW！！！

Anthropic 把每一次對話都完整存在你的本機上，當初不知道他們是怎麼想的，但現在回頭看真的是有先見之明。這些資料能做的事比我原本想像的多太多了，/project-insights 只是其中一種用法

如果你也在用 Claude Code，去翻翻你的 ~/.claude/projects/，你可能會發現自己坐在一座金礦上面

而你最該挖的第一鏟，是你給 Claude 的那份說明書