session-analyzer

セッションアナライザーのスキル

Claude Code のセッション動作を SKILL.md の仕様に照らして検証する事後分析ツールです。

目的

完了したセッションを分析して、次の点を検証します。

1. 期待される動作と実際の動作 - スキルは SKILL.md のワークフローに従いましたか？
2. コンポーネントの呼び出し - SubAgents、Hooks、Tools は正しく呼び出されましたか？
3. 成果物 - 期待されるファイルは作成／削除されましたか？
4. バグの検出 - 想定外のエラーや逸脱はありませんでしたか？

---

入力要件

パラメーター	必須	説明
sessionId	はい	分析するセッションの UUID
targetSkill	はい	検証対象の SKILL.md へのパス
additionalRequirements	いいえ	追加の検証基準

---

フェーズ 1：セッションファイルの検索

ステップ 1.1：セッションファイルを探す

セッションファイルは ~/.claude/ にあります。

# Main session log
~/.claude/projects/-{encoded-cwd}/{sessionId}.jsonl

# Debug log (detailed)
~/.claude/debug/{sessionId}.txt

# Agent transcripts (if subagents were used)
~/.claude/projects/-{encoded-cwd}/agent-{agentId}.jsonl

スクリプトを使ってファイルを探します。

${baseDir}/scripts/find-session-files.sh {sessionId}

ステップ 1.2：ファイルの存在を確認する

続行する前に、必要なファイルがすべて存在することを確認します。デバッグログがない場合、分析は限定的になります。

---

フェーズ 2：対象の SKILL.md を解析する

ステップ 2.1：期待されるコンポーネントを抽出する

対象の SKILL.md を読み、次の項目を特定します。

YAML Frontmatter から：

• hooks.PreToolUse - 期待される PreToolUse フックとマッチャー
• hooks.PostToolUse - 期待される PostToolUse フック
• hooks.Stop - 期待される Stop フック
• hooks.SubagentStop - 期待される SubagentStop フック
• allowed-tools - スキルで使用が許可されているツール

Markdown 本文から：

• 言及されている SubAgents（Task(subagent_type="...")）
• 呼び出されるスキル（Skill("...")）
• 作成される成果物（.dev-flow/drafts/、.dev-flow/plans/ など）
• ワークフローの手順と条件

ステップ 2.2：期待される動作のチェックリストを作成する

SKILL.md の分析結果からチェックリストを作成します。

## Expected Behavior

### SubAgents
- [ ] Explore agent called (parallel, run_in_background)
- [ ] gap-analyzer called before plan generation
- [ ] reviewer called after plan creation

### Hooks
- [ ] PreToolUse[Edit|Write] triggers plan-guard.sh
- [ ] Stop hook validates reviewer approval

### Artifacts
- [ ] Draft file created at .dev-flow/drafts/{name}.md
- [ ] Plan file created at .dev-flow/plans/{name}.md
- [ ] Draft file deleted after OKAY

### Workflow
- [ ] Interview Mode before Plan Generation
- [ ] User explicit request triggers plan generation
- [ ] Reviewer REJECT causes revision loop

---

フェーズ 3：デバッグログを分析する

デバッグログ（~/.claude/debug/{sessionId}.txt）には、詳細な実行トレースが含まれています。

ステップ 3.1：SubAgent の呼び出しを抽出する

パターンを検索します。

SubagentStart with query: {agent-name}
SubagentStop with query: {agent-id}

スクリプトを使います。

${baseDir}/scripts/extract-subagent-calls.sh {debug-log-path}

ステップ 3.2：フックイベントを抽出する

パターンを検索します。

Getting matching hook commands for {HookEvent} with query: {tool-name}
Matched {N} unique hooks for query "{query}"
Hooks: Processing prompt hook with prompt: {prompt}
Hooks: Prompt hook condition was met/not met
permissionDecision: allow/deny

スクリプトを使います。

${baseDir}/scripts/extract-hook-events.sh {debug-log-path}

ステップ 3.3：ツールの呼び出しを抽出する

パターンを検索します。

executePreToolHooks called for tool: {tool-name}
File {path} written atomically

ステップ 3.4：フックの結果を抽出する

プロンプトベースのフックでは、モデルの応答を探します。

Hooks: Model response: {
  "ok": true/false,
  "reason": "..."
}

---

フェーズ 4：成果物を検証する

ステップ 4.1：ファイルの作成を確認する

期待される成果物ごとに、次を行います。

1. デバッグログで FileHistory: Tracked file modification for {path} を検索します
2. File {path} written atomically を検索します
3. 現在のファイルシステムの状態を確認します

ステップ 4.2：ファイルの削除を確認する

削除されるはずのファイルについて、次を行います。

1. Bash 呼び出し内の rm コマンドを検索します
2. ファイルがファイルシステム上に残っていないことを確認します

---

フェーズ 5：期待される動作と実際の動作を比較する

ステップ 5.1：比較表を作成する

| Component | Expected | Actual | Status |
|-----------|----------|--------|--------|
| Explore agent | 2 parallel calls | 2 calls at 09:39:26 | ✅ |
| gap-analyzer | Called before plan | Called at 09:43:08 | ✅ |
| reviewer | Called after plan | 2 calls (REJECT→OKAY) | ✅ |
| PreToolUse hook | Edit\|Write matcher | Triggered for Write | ✅ |
| Stop hook | Validates approval | Returned ok:true | ✅ |
| Draft file | Created then deleted | Created→Deleted | ✅ |
| Plan file | Created | Exists (10KB) | ✅ |

ステップ 5.2：逸脱を特定する

不一致があれば、次の項目に印を付けます。

• コンポーネント呼び出しの欠落
• 操作順序の誤り
• フックの失敗
• 成果物の欠落
• 想定外のエラー

---

フェーズ 6：レポートを生成する

レポートテンプレート

# Session Analysis Report

## Session Info
- **Session ID**: {sessionId}
- **Target Skill**: {skillPath}
- **Analysis Date**: {date}

---

## 1. Expected Behavior (from SKILL.md)

[Summary of expected workflow]

---

## 2. Skill/SubAgent/Hook Verification

### SubAgents
| SubAgent | Expected | Actual | Time | Result |
|----------|----------|--------|------|--------|
| ... | ... | ... | ... | ✅/❌ |

### Hooks
| Hook | Matcher | Triggered | Result |
|------|---------|-----------|--------|
| ... | ... | ... | ✅/❌ |

---

## 3. Artifacts Verification

| Artifact | Path | Expected State | Actual State |
|----------|------|----------------|--------------|
| ... | ... | ... | ✅/❌ |

---

## 4. Issues/Bugs

| Severity | Description | Location |
|----------|-------------|----------|
| ... | ... | ... |

---

## 5. Overall Result

**Verdict**: ✅ PASS / ❌ FAIL

**Summary**: [1-2 sentence summary]

---

スクリプトの参照

スクリプト	用途
find-session-files.sh	セッション ID に対応するすべてのファイルを検索します
extract-subagent-calls.sh	デバッグログからサブエージェントの呼び出しを解析します
extract-hook-events.sh	デバッグログからフックイベントを解析します

---

使用例

User: "Analyze session 3cc71c9f-d27a-4233-9dbc-c4f07ea6ec5b against .claude/skills/specify/SKILL.md"

1. Find session files
2. Parse SKILL.md → Expected: Explore, gap-analyzer, reviewer, hooks
3. Analyze debug log → Extract actual calls
4. Verify artifacts → Check .dev-flow/
5. Compare → Build verification table
6. Generate report → PASS/FAIL with details

---

追加リソース

参照ファイル

• references/analysis-patterns.md - ログ分析用の詳細な grep パターン
• references/common-issues.md - 既知の問題とトラブルシューティング

スクリプト

• scripts/find-session-files.sh - セッションファイルの検索ツール
• scripts/extract-subagent-calls.sh - SubAgent 呼び出しの抽出ツール
• scripts/extract-hook-events.sh - フックイベントの抽出ツール