debug-log-analysis

モード：認知／プロンプト駆動型 — 単独のユーティリティスクリプトはありません。エージェントのコンテキストから使用します。

デバッグログ分析

Claude Code セッションのデバッグログから、実用的なシグナルを抽出するための構造化ワークフローです。振り返りサイクル、インシデント対応、エージェントの障害診断時に使用します。

使用するタイミング

• エージェントの予期しない失敗や停止が発生したセッションの後
• reflection-agent がタスク完了の状況を把握するためのテレメトリーを必要とするとき
• タスク出力では原因が分かりにくいフックエラーをデバッグするとき
• ルーターから「エージェントは完了したが TaskUpdate を呼び出していない」と報告されたとき

前提条件

scripts/reduce-debug-log.mjs スクリプトは、ファイル引数が指定されていない場合、最新のログを自動検出します。ログを .tmp/ にコピーし、そこで縮小版を生成します。

ステップ 0：分析モードを決定する

利用できるモードは 2 つです。

自動モード（推奨）： pnpm debug:reduce に最新のログを自動で検索・処理させます。

手動モード： 特定のセッション UUID またはログファイルのパスを指定します。

ステップ 1：デバッグログを特定して縮小する

重要：必ず最新のログを動的に検索してください。セッション UUID をハードコードしないでください。

自動モード（推奨）

# Auto-detect most recent log, copy to .tmp/, reduce in place
cd /c/dev/projects/agent-studio && node scripts/reduce-debug-log.mjs 2>&1

# The script prints:
# Auto-detected debug log: /home/user/.claude/debug/{session-uuid}.txt
# Copied to: .tmp/{session-uuid}.txt
# Original: N lines -> kept (issue-like): M -> ... -> after dedupe: K
# Output: .tmp/{session-uuid}-reduced.txt

以降のステップで使うため、スクリプト出力から出力先のパスを取得します。

手動モード（特定のセッションが必要な場合）

# List recent debug logs sorted by modification time (most recent first)
ls -t "$HOME/.claude/debug/"*.txt 2>/dev/null | head -5

# Or on Windows (Git Bash):
ls -t "$USERPROFILE/.claude/debug/"*.txt 2>/dev/null | head -5

対象のログパスを選び、次を実行します。

# Copy to temp (never operate on the original)
mkdir -p .claude/context/tmp
cp "$HOME/.claude/debug/{session-uuid}.txt" ".claude/context/tmp/debug-session-copy.txt"

# Run reducer with explicit output path
node scripts/reduce-debug-log.mjs \
  ".claude/context/tmp/debug-session-copy.txt" \
  --output ".claude/context/tmp/debug-session-reduced.txt"

縮小に成功したことを確認する

# Check sizes
wc -l ".claude/context/tmp/debug-session-copy.txt"
wc -l ".claude/context/tmp/debug-session-reduced.txt"

想定：縮小後のファイルは、元の行数の 1～5％です（ノイズを 98％以上除去）。

ステップ 2：元のログと縮小版を比較する

フィルターの品質を把握するため、除外された内容を計算します。

ORIGINAL_LINES=$(wc -l < ".claude/context/tmp/debug-session-copy.txt")
REDUCED_LINES=$(wc -l < ".claude/context/tmp/debug-session-reduced.txt")
echo "Original: $ORIGINAL_LINES lines | Reduced: $REDUCED_LINES lines"
echo "Kept: $(echo "scale=1; $REDUCED_LINES * 100 / $ORIGINAL_LINES" | bc)%"

異常があれば記録します。たとえば、縮小率が 90％未満の場合、そのセッションでは通常より多くのエラーが発生しています。

ステップ 3：縮小ログを読む

.claude/context/tmp/debug-session-reduced.txt をすべて読みます。

ステップ 4：縮小ログのエラーパターンを分類する

縮小ログの各行を、次のように分類します。

カテゴリー	シグナルパターン	アクション
フックによるブロック（Write）	PreToolUse:Write + block	件数を数え、トリガーしたエージェントとファイルパスを特定する
フックによるブロック（TaskUpdate）	PreToolUse:TaskUpdate + burst	件数を数え、ループしているエージェントを特定する
読み込み対象なし	File does not exist またはプレースホルダーテキスト	件数を数え、見つからないファイルを列挙する
トークン超過	FileTooLargeError または token limit	件数を数え、大きなファイルを特定する
ストリーミング停止	ログエントリー間の間隔が 60 秒超	継続時間を合計し、停止直前の内容を記録する
エージェント脱落	TaskUpdate not called または完了せずに agent returned	タスク ID ごとに列挙する
ツールエラー	EISDIR、ENOENT、sibling tool call errored	ツールごとに分類する

ステップ 5：上位のエラーを完全なログと照合する

発生頻度の高いエラーカテゴリーの上位 3 つについて、次を行います。

1. 完全な（未縮小の）ログコピーから、エラーのシグネチャを grep する
2. 発生箇所の前後 10 行を確認する
3. どのツール呼び出しがエラーを引き起こしたか、どのエージェントが実行中だったか、そのエージェントが何をしようとしていたかを特定する

# Use the full copy (not the original, not the reduced)
grep -n "PreToolUse:Write" ".claude/context/tmp/debug-session-copy.txt" | head -30
grep -n "File does not exist" ".claude/context/tmp/debug-session-copy.txt" | head -30
grep -n "timeout" ".claude/context/tmp/debug-session-copy.txt" -i | head -30

ステップ 6：一時ファイルを削除する

分析後、作業用コピーを削除します（レポートに必要な場合は縮小ファイルを残します）。

rm -f ".claude/context/tmp/debug-session-copy.txt"
# Optionally keep the reduced file for reference; delete when done
# rm -f ".claude/context/tmp/debug-session-reduced.txt"

ステップ 7：構造化レポートを作成する

.claude/context/reports/reflections/debug-log-analysis-{YYYY-MM-DD}.md に書き込みます。

# Debug Log Analysis — {YYYY-MM-DD}

**Source log:** {path to original log — auto-detected or provided}
**Session UUID:** {session-uuid extracted from filename}
**Log statistics:**

- Original: {N} lines / {bytes} bytes
- Reduced: {M} lines / {bytes} bytes
- Reduction ratio: {X}%
  **Analysis timestamp:** {ISO-8601}

## Error Summary

| Category           | Count | Severity | Root Cause |
| ------------------ | ----- | -------- | ---------- |
| Hook Block (Write) | N     | CRITICAL | ...        |
| Read Miss          | N     | HIGH     | ...        |
| ...                |       |          |            |

## Top 3 Deep Dives

### 1. {Most frequent error}

**Frequency:** N occurrences
**First occurrence:** line {N}, timestamp {T}
**Context:** {what the agent was doing}
**Root cause:** {why it happened}
**Fix:** {concrete recommendation}

### 2. ...

### 3. ...

## Observability Gaps Found

List any gaps where the log entry doesn't have enough info to diagnose the error.

## Recommendations

- [ ] Immediate P0: {fix}
- [ ] P1: {fix}
- [ ] P2: {fix}

既知の可観測性のギャップ（Agent-Studio v2026-02）

現在のデバッグログ形式には、次のギャップがあります。

1. フックによる拒否の本文が記録されない — unified-creator-guard.cjs が Write をブロックしても、拒否理由はデバッグログに記録されません。PreToolUse:Write blocked は表示されますが、理由はわかりません。

   • 回避策：process.stderr の出力を別途確認するか、フックのソースを読んで、どのルールが適用されたかを推測します。

2. エラー行にエージェントの識別情報がない — エラー行には、どのスポーンされたエージェントがエラーを引き起こしたかが含まれていません。

   • 回避策：タスクの起動／完了ログとタイムスタンプを照合します。

3. Read の失敗時にファイルパスが省略される — File does not exist の行には、ファイルパスが記載されないことがあります。

   • 回避策：直前のツール呼び出し行で、試行されたパスを確認します。

4. ストリーミングの停止の原因を特定できない — 5 分以上の停止は、コンテキストのないタイムスタンプの空白として表示されます。

   • 回避策：空白の直前のツール呼び出しが、原因である可能性が高いです。

5. 成功のログがない — 目立つのは失敗のみです。ツール呼び出しが成功しても、ログエントリは最小限です。

   • 回避策：タスクの概要メタデータから、ツールの総使用回数を数えます。

Reflection との連携

Reflection エージェントは、優先度が HIGH の Reflection リクエストに対して、このスキルを呼び出してください。

// In reflection agent, for high-priority triggers:
if (priority === 'high' && debugLogPath) {
  Skill({ skill: 'debug-log-analysis' });
  // Include findings in reflection report
}

絶対に守るべきルール

1. 必ず分析を始める前にデバッグログをコピーしてください。元のファイルを直接操作してはいけません。インプレース操作はフォレンジック証拠を破損させます。
2. 絶対にgrep の単一の一致だけを根拠に根本原因を報告してはいけません。エージェントが実際に何をしていたかを把握するため、一致箇所の前後それぞれ少なくとも10行のコンテキストを必ず読んでください。
3. 必ず完全なデバッグログを読もうとする前に、ログ削減スクリプト（ステップ2）を実行してください。フィルターされていないデバッグログには98％以上のノイズが含まれており、実際のシグナルが埋もれてしまいます。
4. 絶対に構造化エラーレポート（ステップ6）を省略してはいけません。口頭での非公式な概要は成果物ではありません。Reflection エージェントが調査結果を取り込むには、Markdown レポートが必要です。
5. 必ず新たに見つかった再発性のエラーパターンを .claude/context/memory/issues.md に記録してください。記憶に書かれていないパターンは、セッションをまたいで気づかれないまま再発します。

アンチパターン

アンチパターン	失敗する理由	正しい方法
元のログファイルを直接 grep する	タイムスタンプを変更し、フォレンジック証拠を破損させ、ロールバックできません	必ず先にコピーします：cp debug.txt .claude/context/tmp/debug-{date}.txt
削減していないログ全体を読む	ノイズ対シグナル比が98％以上で、分析に何時間もかかり、パターンを見落とします	先に reduce-debug-log.mjs を実行し、削減後の出力を使います
grep の単一の一致から根本原因を報告する	単一の一致は、無関係なツール呼び出しによる誤検出であることがよくあります	根本原因を結論づける前に、すべての一致箇所の前後±10行のコンテキストを読みます
レポートの代わりに非公式な口頭の概要を伝える	Reflection エージェントは、非公式な概要をメモリーエントリに解析できません	構造化された完全な Markdown レポートを .claude/context/reports/reflections/ に書きます
分析後にメモリーへの記録を省略する	エラーパターンが気づかれないまま再発し、組織としての学びが蓄積されません	タスク完了前に、新たなパターンをすべて issues.md または learnings.md に記録します

メモリープロトコル（必須）

完了後：

• 新しいエラーパターンを発見した場合 → .claude/context/memory/issues.md
• 新しい可観測性のギャップを発見した場合 → .claude/context/memory/issues.md
• セッションをまたいで再発するパターン → .claude/context/memory/learnings.md

中断を前提としてください。メモリーに記録されていなければ、起きていないのと同じです。