debug-hooks

デバッグフック

Claude Code フックの体系的なデバッグワークフローです。

使用するタイミング

• 「フックが実行されない」
• 「フックが誤った出力を生成する」
• 「SessionEnd が機能しない」
• 「PostToolUse フックが起動しない」
• 「フックが実行されなかったのはなぜ？」

ワークフロー

1. まず出力を確認する（編集する前に状態を観察する）

# Check project cache
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/

# Check specific outputs
ls -la $CLAUDE_PROJECT_DIR/.claude/cache/learnings/

# Check for debug logs
tail $CLAUDE_PROJECT_DIR/.claude/cache/*.log 2>/dev/null

# Also check global (common mistake: wrong path)
ls -la ~/.claude/cache/ 2>/dev/null

2. フックの登録を確認する

# Project settings
cat $CLAUDE_PROJECT_DIR/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

# Global settings (hooks merge from both)
cat ~/.claude/settings.json | grep -A 20 '"SessionEnd"\|"PostToolUse"\|"UserPromptSubmit"'

3. フックファイルが存在することを確認する

# Shell wrappers
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/*.sh

# Compiled bundles (if using TypeScript)
ls -la $CLAUDE_PROJECT_DIR/.claude/hooks/dist/*.mjs

4. フックを手動でテストする

# SessionEnd hook
echo '{"session_id": "test-123", "reason": "clear", "transcript_path": "/tmp/test"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/session-end-cleanup.sh

# PostToolUse hook (Write tool example)
echo '{"tool_name": "Write", "tool_input": {"file_path": "test.md"}, "session_id": "test-123"}' | \
  $CLAUDE_PROJECT_DIR/.claude/hooks/handoff-index.sh

5. サイレントエラーを確認する

stdio: 'ignore' を指定してデタッチされたプロセスを起動している場合：

// This pattern hides errors!
spawn(cmd, args, { detached: true, stdio: 'ignore' })

修正方法： 一時的なログ出力を追加します。

const logFile = fs.openSync('.claude/cache/debug.log', 'a');
spawn(cmd, args, {
  detached: true,
  stdio: ['ignore', logFile, logFile]  // capture stdout/stderr
});

6. 編集後に再ビルドする

TypeScript のソースを編集した場合は、必ず再ビルドしてください。

cd $CLAUDE_PROJECT_DIR/.claude/hooks
npx esbuild src/session-end-cleanup.ts \
  --bundle --platform=node --format=esm \
  --outfile=dist/session-end-cleanup.mjs

ソースを編集しただけでは反映されません。シェルラッパーはバンドル済みの .mjs を実行します。

よくある問題

症状	考えられる原因	修正方法
フックが一度も実行されない	settings.json に登録されていない	設定内の正しいイベントに追加する
フックは実行されるが、出力がない	デタッチされたプロセスがエラーを隠している	ログ出力を追加し、手動で確認する
セッション ID が違う	「最新」のクエリを使用している	ID を明示的に渡す
ローカルでは動作するが、CI では動作しない	依存関係が不足している	npx/node が利用可能か確認する
2 回実行される	グローバルとプロジェクトの両方に登録されている	重複を削除する

デバッグチェックリスト

• 出力は存在するか？（ls -la .claude/cache/）
• 登録されているか？（grep -A10 '"hooks"' .claude/settings.json）
• ファイルは存在するか？（ls .claude/hooks/*.sh）
• バンドルは最新か？（ls -la .claude/hooks/dist/）
• 手動テストは成功するか？（echo '{}' | ./hook.sh）
• サイレントエラーはないか？（stdio: 'ignore' がないか確認する）

ソースセッション

10 件のセッション（学習内容全体の 83%）をもとに作成：

• a541f08a, 1c21e6c8, 6a9f2d7a, a8bd5cea, 2ca1a178, 657ce0b2, 3998f3a2, 2a829f12, 0b46cfd7, 862f6e2c