記錄分析
分析 Claude Code JSONL 工作階段記錄，以偵測反模式、效率低下以及工作流程改善機會。
資料位置
記錄位於 ~/.claude/projects/ 下，按專案路徑命名的專案專用目錄中（路徑中的斜線替換為連字號）。
DuckDB 的作用： 透過 get_transcript_jsonl_schema 或 MCP resources/read kaizen://session-log/schema 載入來自 kaizen-analysis 的完整欄位/路徑參考，然後使用 kaizen-duckdb execute_query 對這些檔案執行任何 DuckDB SQL（請參閱 DuckDB 查詢模式 以取得範例和任意查詢工作流程）。工作階段歷史記錄以 JSONL 格式保留在磁碟上。DuckDB MCP 的路徑規則請參閱跨平台備註（使用絕對路徑，SQL 中不要使用 ~）。
~/.claude/projects/{project-key}/
├── {uuid}.jsonl # 主要工作階段記錄
├── agent-{id}.jsonl # 孤立代理記錄
└── {uuid}/
├── subagents/
│ └── agent-{id}.jsonl # 子代理記錄
└── tool-results/
└── {tool-use-id}.txt # 非同步任務輸出
JSONL 記錄類型
每一行 JSONL 都是一個 JSON 物件，由 type 欄位區分。
主要的分析記錄類型：
assistant— 包含工具呼叫和文字的 LLM 回應回合user— 人類輸入和工具結果system— 中繼資料事件 (stop_hook_summary, turn_duration, compact_boundary, api_error, local_command)progress— 鉤子執行和子代理串流file-history-snapshot— 檔案編輯追蹤summary— 工作階段標題/摘要
有關每種記錄類型的完整 JSON 結構等詳細資訊，請參閱 JSONL 結構參考。
訊號目錄
以下每個分析維度都有其自己的提取方法。
1. 工具誤用偵測
從 assistant.message.content[] 中提取 name == "Bash" 的項目。解析 input.command 中應使用內建工具的檔案操作模式。關於 SQL 提取查詢，請參閱 DuckDB 查詢模式。
解析 tool_use 區塊中的 Bash 指令，比對：
grep→ 應使用 Grep 工具find -name→ 應使用 Glob 工具cat,head,tail→ 應使用 Read 工具ls→ 應使用 Glob 或 Bash(ls) 並附上說明sed,awk→ 應使用 Edit 工具
排除管線中的合法用途 (git ... | grep, uv run ... | head)。
2. 重複錯誤
從 is_error: true 的工具結果中提取。分類錯誤類型：
- "File has not been read yet" — 先編輯後讀取的反模式
- "String to replace not found" — 過時的編輯目標
- "User denied tool use" — 權限/信任問題
- 提交前鉤子失敗 (exit code 1)
- 缺少二進位檔 / 找不到指令
3. 缺失工具機會
透過工具序列三元組分析，識別跨工作階段重複的多步驟手動工作流程。高頻率的三元組，例如 Bash → Bash → Bash 或 Read → Read → Read，表示缺少腳本或技能。
4. 子代理委派模式
從 Task 的 tool_use 區塊中提取。追蹤 subagent_type、description、model。當有專門代理可用卻使用 general-purpose 時，標記為異常。
5. 最短路徑分析
比較相同目標的成功與失敗嘗試。測量從目標陳述（使用者回合）到成功結果（最終助理回合）之間的工具呼叫次數。對於相似目標，跨工作階段的變異數過高表示存在浪費的步驟。
6. 誤導偵測
追蹤被放棄的調查分支。訊號：針對某主題的一系列 Read/Grep/Bash 呼叫，之後緊接著 compact_boundary 或方向變更，且未解決問題。相同放棄路徑的跨工作階段頻率揭示了系統性的誤導。
7. 系統流程中斷
提取 system.compact_boundary、system.api_error 以及與鉤子相關的 progress 事件。繪製其相對於進行中工作的位置，以識別系統流程何時偏離了正確的執行路徑。
8. 缺失鉤子
識別跨工作階段重複出現的手動修正。當相同的修正出現 3 次或以上時，就適合透過 PreToolUse 鉤子（拒絕 + 重新導向）或 SubagentStart 鉤子（注入上下文）進行自動化預防。
9. DuckDB SQL 查詢
使用 kaizen-analysis get_transcript_jsonl_schema 或資源 kaizen://session-log/schema 取得完整路徑參考，然後使用 kaizen-duckdb execute_query 對 JSONL 執行任何 SQL（使用絕對路徑的 read_ndjson_auto）。您不受食譜查詢的限制。
如需任意查詢工作流程和範例，請參閱 DuckDB 查詢模式。
流程探勘方法論
使用 kaizen-analysis MCP 伺服器工具來處理 SQL 無法表達的分析：
extract_tool_sequences— 將 JSONL 轉換為每個工作階段的排序工具呼叫陣列discover_process_model— 在工具呼叫序列上建立輕量級轉換模型check_conformance— 將會話與參考流程模型進行比較find_frequent_patterns— PrefixSpan 序列模式挖掘cluster_sessions— 按行為相似性進行軌跡聚類
分析工作流程
flowchart TD
Start([接收分析任務]) --> Scope{範圍已定義?}
Scope -->|--project 旗標| Project[過濾到專案記錄]
Scope -->|無旗標| Default[使用當前專案]
Project --> Discover[SQL — 計數工作階段、日期範圍、記錄類型]
Default --> Discover
Discover --> Dimensions{哪些維度?}
Dimensions -->|全部| RunAll[執行所有維度]
Dimensions -->|指定| RunSelected[執行指定維度]
RunAll --> Aggregate[彙總發現]
RunSelected --> Aggregate
Aggregate --> Write[寫入 .planning/kaizen/analysis-DATE.md]
輸出格式
將分析發現寫入 .planning/kaizen/ 目錄下，格式為結構化的 Markdown，包含：
- 每個發現的工作階段 ID 和日期
- 嚴重性 (critical / warning / info)
- 證據 — 確切的 JSON 欄位路徑和值
- 頻率 — 表現出該模式的工作階段數量
- 建議類型 — 鉤子、技能修補、代理提示修正、CLAUDE.md 更新