Jamie-BitFlight/transcript-analysis

トランスクリプト分析

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          # 孤立したエージェントトランスクリプト
└── {uuid}/
    ├── subagents/
    │   └── agent-{id}.jsonl  # サブエージェントトランスクリプト
    └── tool-results/
        └── {tool-use-id}.txt # 非同期タスク出力

JSONLレコードタイプ

各JSONL行は type フィールドで識別されるJSONオブジェクトです。

分析における主要なレコードタイプ:

• 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 クエリパターン を参照してください。

以下の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 を追跡します。特殊エージェントが存在する場面で 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 クエリパターンを参照してください。

プロセスマイニング手法

SQLでは表現できない分析には、kaizen-analysis MCPサーバーツールを使用します:

• 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更新