introspect

詳細分析

Claude Code のセッションログから、実行可能なインテリジェンスを抽出します。一般的な JSONL 分析パターン（フィルタリング、集計、複数ファイル間の結合）については、log-ops スキルを参照してください。

cc-session CLI

scripts/cc-session スクリプトは、依存関係なしで分析を行えます（jq と bash のみが必要です）。現在のプロジェクトと最新のセッションを自動的に特定します。

# Copy to PATH for global access
cp skills/introspect/scripts/cc-session ~/.local/bin/
# Or on Windows (Git Bash)
cp skills/introspect/scripts/cc-session ~/bin/

コマンド

コマンド	内容
cc-session overview	エントリ数、時間、ツール／思考の合計
cc-session tools	ツール使用頻度（ソート済み）
cc-session tool-chain	入力の概要を含む、ツール呼び出しの順次トレース
cc-session thinking	思考／推論ブロック全体
cc-session thinking-summary	各思考ブロックの先頭 200 文字
cc-session errors	エラーパターンを含むツール結果
cc-session conversation	ユーザー／アシスタントのやり取りを再構成
cc-session files	読み取り、編集、書き込みを行ったファイル（件数付き）
cc-session turns	ターンごとの内訳（所要時間、使用したツール）
cc-session agents	サブエージェントの起動情報（タイプ、プロンプトのプレビュー付き）
cc-session cost	トークン数／コストの概算
cc-session timeline	タイムスタンプ付きのイベントタイムライン
cc-session summary	セッションの要約（コンパクションの境界）
cc-session search <pattern>	セッション全体を検索（テキスト内容）

オプション

--project, -p <name>    Filter by project (partial match)
--dir, -d <pattern>     Filter by directory pattern in project path
--all                   Search all projects (with search command)
--recent <n>            Use nth most recent session (default: 1)
--json                  Output as JSON instead of text

使用例

cc-session overview                              # Current project, latest session
cc-session tools --recent 2                      # Tools from second-latest session
cc-session tool-chain                            # Full tool call sequence
cc-session errors -p claude-mods                 # Errors in claude-mods project
cc-session thinking | grep -i "decision"         # Search reasoning
cc-session search "auth" --all                   # Search all projects
cc-session turns --json | jq '.[] | select(.tools > 5)'  # Complex turns
cc-session files --json | jq '.edited[:5]'       # Top 5 edited files
cc-session overview --json                       # Pipe to other tools

分析の判断ツリー

What do you want to know?
|
|- "What happened in a session?"
|  |- Quick overview ---- cc-session overview
|  |- Full conversation -- cc-session conversation
|  |- Timeline ---------- cc-session timeline
|  |- Summaries --------- cc-session summary
|
|- "How was I using tools?"
|  |- Frequency ---------- cc-session tools
|  |- Call sequence ------- cc-session tool-chain
|  |- Files touched ------- cc-session files
|
|- "What was I thinking?"
|  |- Full reasoning ------ cc-session thinking
|  |- Quick scan ---------- cc-session thinking-summary
|  |- Topic search -------- cc-session thinking | grep -i "topic"
|
|- "What went wrong?"
|  |- Tool errors --------- cc-session errors
|  |- Debug trajectory ---- cc-session tool-chain (trace the sequence)
|
|- "Compare sessions"
|  |- Tool usage diff ----- cc-session tools --recent 1 vs --recent 2
|  |- Token estimation ---- cc-session cost
|
|- "Search across sessions"
|  |- Current project ----- cc-session search "pattern"
|  |- All projects -------- cc-session search "pattern" --all

セッションログのスキーマ

ファイル構造

~/.claude/
|- projects/
|   |- {project-path}/                        # e.g., X--Forge-claude-mods/
|       |- sessions-index.json                # Session metadata index
|       |- {session-uuid}.jsonl               # Full session transcript
|       |- agent-{short-id}.jsonl             # Subagent transcripts

プロジェクトのパスには、二重ハイフンによるエンコードが使われます。C:\Projects\my-repo → C--Projects-my-repo

エントリタイプ

タイプ	ロール	主なフィールド
user	ユーザーメッセージとツール結果	message.content[].type = "text" または "tool_result"
assistant	Claude の応答	message.content[].type = "text"、"tool_use"、または "thinking"
system	ターン所要時間、コンパクション	subtype = "turn_duration"（durationMs を含む）または "compact_boundary"
progress	フック／ツールの進行状況イベント	data.type、toolUseID、parentToolUseID
file-history-snapshot	ファイル状態のチェックポイント	snapshot、messageId、isSnapshotUpdate
queue-operation	メッセージキューのイベント	operation、content
last-prompt	最後のユーザープロンプトのキャッシュ	lastPrompt
summary	コンパクションの要約	summary、leafUuid

コンテンツブロックのタイプ（message.content[] 内）

ブロックタイプ	含まれる場所	フィールド
text	user、assistant	.text
tool_use	assistant	.id、.name、.input
tool_result	user	.tool_use_id、.content
thinking	assistant	.thinking、.signature

共通フィールド（すべてのエントリタイプ）

uuid, parentUuid, sessionId, timestamp, type,
cwd, gitBranch, version, isSidechain, userType

セッションログの保持期間

デフォルトでは、Claude Code は起動時に、30 日間非アクティブなセッションを削除します。分析用に履歴を保持するには、この期間を延長してください。

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 90
}

現在は 90 日に設定されています。ディスク使用量に応じて調整してください（dust -d 1 ~/.claude/projects/）。

jq クイックリファレンス

cc-session で対応できない内容を個別にクエリする場合は、次を参照してください。

# Pipe through cat on Windows (jq file args can fail)
cat session.jsonl | jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name'

# Two-stage for large files
rg '"tool_use"' session.jsonl | jq -r '.message.content[]? | select(.type == "tool_use") | .name'

セッションインサイト

分析を実行した後は、実行可能な提案を含む「セッションインサイト」セクションを必ず作成してください。批判的な口調ではなく、パターンに気づいた親切な同僚が、役立つ助言をするような、親しみやすく指導的な口調にしてください。

注目するポイント

セッションデータを確認し、該当する場合は次のパターンをもとに推奨事項を作成します。

ツール使用の改善：

• Grep／Read ツールではなく Bash(grep ...) や Bash(cat ...) を使用している場合は、専用ツールの使用を提案します
• 同じ入力でツール呼び出しを繰り返し失敗している場合は、より早い段階で別の方法に切り替えるよう提案します
• スキルで対応できるタスクに Bash を多用している場合は、スキル名を挙げて利用を勧めます
• 独立した読み取りや検索を並行して実行できるのに、並列ツール呼び出しを利用していない場合は指摘します

ワークフローのパターン：

• コミットのない長時間セッションでは、こまめなコミットを提案します
• セッション終了時に /save を使っていない場合は、セッションの継続性を保つよう促します
• 同じファイルを3回以上読み直している場合は、メモを残すか /save を使うよう提案します
• /iterate で自動化できる手作業が大量にある場合は、ループパターンに触れます
• 同じ方法で5回以上試行してデバッグが堂々巡りになっている場合は、3回試したら別の方法に切り替えるルールを提案します

スキルとコマンドの把握：

• /review を使わずに手動でコードレビューを行っている場合は、そのスキルに触れます
• /testgen を使わずにテストを作成している場合は、そのスキルに触れます
• 複雑な推論が必要なのに /atomise を使っていない場合は、難しい問題に対する利用を提案します
• スキルで対応できるタスクにエージェントを起動している場合は、より手軽な方法を提案します

セッション効率：

• 非常に長いセッション（ツール呼び出し100回以上）では、目的を絞ったセッションに分割するよう提案します
• エラー率が高い（ツール呼び出しの30％超がエラー）場合は、そのパターンを指摘し、原因の調査を提案します
• 編集に対してファイルの読み取りが過剰な場合（比率が10:1超）は、迷いが生じている可能性があるため、先に計画を立てるよう提案します

権限に関する推奨事項： これは特に有用です。権限の確認プロンプトは作業の流れを妨げ、コンテキストを消費します。セッションを確認して、次の点を調べます。

• 正常に繰り返し実行された Bash コマンド。Bash(<command>:*) の許可ルール候補です
• 頻繁に使われたツールパターン（WebFetch、WebSearch、特定の MCP ツール）。許可リストへの追加を提案します
• 権限エラーで失敗した、または再試行されたコマンド。権限の不足によってブロックされた可能性があります

.claude/settings.local.json に貼り付けて使える permissions.allow のスニペットを作成します。

**Permissions**

Based on this session, these tools were used frequently and could be
pre-approved to reduce interruptions:

Add to `.claude/settings.local.json` under `permissions.allow`:
  "Bash(uv:*)",
  "Bash(pytest:*)",
  "Bash(docker:*)",
  "WebSearch",
  "mcp__my-server__*"

This would have saved roughly ~N permission prompts in this session.

実際に正常に使用されたコマンドのみを推奨し、包括的な Bash(*) は決して提案しないでください。ただし、適切な場合はワイルドカードパターンを積極的に推奨します。Bash(git status)、Bash(git add)、Bash(git commit) を個別に列挙するより、Bash(git:*) のほうが適切です。よく使われるワイルドカードのグループは次のとおりです。

• Bash(git:*) - すべての git 操作
• Bash(npm:*)、Bash(pnpm:*)、Bash(uv:*) - パッケージマネージャー
• Bash(pytest:*)、Bash(jest:*) - テストランナー
• Bash(docker:*)、Bash(cargo:*)、Bash(go:*) - ビルド／ランタイムツール
• mcp__server-name__* - MCP サーバーのすべてのツール

分かりやすいように、推奨事項をカテゴリごとにまとめます。リストが長い場合は、権限をすべて設定する方法として /setperms を案内してください。

出力形式

## Session Insights

Here are a few things I noticed that might help next time:

**[Category]**
- [Observation]: [What was seen in the data]
- [Suggestion]: [Friendly, specific recommendation]

**[Category]**
- ...

推奨事項の数は、セッションの規模に合わせてください。10分程度の短いセッションなら、所見は1～2件が妥当です。100回以上のツール呼び出しを伴う数時間の大規模なセッションなら、実行可能な洞察を10～15件挙げてもよいでしょう。分析の深さは、セッションの規模に合わせてください。

データに明確に表れているパターンのみを挙げ、推測や過度な拡大解釈は避けてください。セッションに問題がなく効率的だった場合は、次のように伝えます。「適切に構成されたセッションです。改善が必要と思われる点は特に見当たりません。」

参考ファイル

ファイル	内容
scripts/cc-session	CLI ツール。14種類のコマンドによるセッション分析、JSON 出力、プロジェクトのフィルタリング
references/session-analysis.md	cc-session では対応できないカスタム分析向けの jq レシピ

関連項目

• log-ops - 一般的な JSONL 処理、2段階のパイプライン、ファイル間の相関分析
• data-processing - jq と yq による JSON／YAML／TOML の処理