转录分析
分析 Claude Code JSONL 会话转录，以检测反模式、低效操作和工作流改进机会。
数据位置
转录文件位于 ~/.claude/projects/ 下以项目路径命名的目录中（斜杠替换为连字符）。
DuckDB 的作用： 通过 kaizen-analysis 的 get_transcript_jsonl_schema 或 MCP 的 resources/read kaizen://session-log/schema 加载完整的字段/路径参考，然后使用 kaizen-duckdb 的 execute_query 对文件运行 任意 DuckDB SQL（示例和任意查询工作流请参见 DuckDB 查询模式）。会话历史保留在磁盘上的 JSONL 文件中。DuckDB MCP 的路径规则（使用绝对路径，SQL 中不能使用 ~）。
~/.claude/projects/{project-key}/
├── {uuid}.jsonl # 主会话转录
├── agent-{id}.jsonl # 孤立 Agent 转录
└── {uuid}/
├── subagents/
│ └── agent-{id}.jsonl # 子 Agent 转录
└── 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— 钩子执行和子 Agent 流式传输file-history-snapshot— 文件编辑追踪summary— 会话标题/摘要
有关包括每种记录类型的 JSON 结构在内的完整模式详细信息，请参见 JSONL 模式参考。
信号目录
以下每个分析维度都有其自己的提取方法。
1. 工具误用检测
从 assistant.message.content[] 中提取 name == "Bash" 的部分。解析 input.command 中应使用内置工具的文件操作模式。有关 SQL 提取查询，请参见 DuckDB 查询模式。
解析与以下内容匹配的 Bash 命令的 tool_use 块：
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 的工具结果中提取。分类错误类型：
- “文件尚未读取” — 先编辑后读取的反模式
- “未找到要替换的字符串” — 过时的编辑目标
- “用户拒绝工具使用” — 权限/信任问题
- 预提交钩子失败（退出码 1）
- 缺少二进制文件 / 命令未找到
3. 缺失工具化机会
通过跨会话的工具序列三元组分析识别重复的多步骤手动工作流。高频三元组如 Bash → Bash → Bash 或 Read → Read → Read 提示缺少脚本或技能。
4. 子代理委派模式
从 Task 工具的 tool_use 块中提取。跟踪 subagent_type、description、model。标记在存在专门 Agent 时仍使用 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-日期.md]
输出格式
将分析发现写入 .planning/kaizen/ 目录，格式为结构化 Markdown，包含：
- 每个发现的会话 ID 和日期
- 严重性（严重 / 警告 / 信息）
- 证据 — 精确的 JSON 字段路径和值
- 频率 — 出现该模式的会话数量
- 建议类型 — 钩子、技能补丁、Agent 提示修复、CLAUDE.md 更新