はじめに
Claudeにエラーを渡して「直して」と頼むと、一瞬で直ったように見えた。しかし5分後に同じエラーが別の形で再発した——そんな経験がある人は少なくないはずだ。
「Claudeのデバッグが表面的で根本解決しない」という感覚の正体は、デバッグセッションの設計の問題だ。「とりあえず直してみる」から始まるアプローチはStep 3（修正）から動き始めるため、根本原因を見つけないまま対処療法を積み重ねる悪循環が起きる。
本記事ではデバッグを「再現→分離→修正→検証」の4ステップで体系化し、/debugスキル・視覚的デバッグ・MCPデバッグ・自己修正ループを組み合わせた実践的なフルサイクルを解説する。
デバッグの4ステップフレームワーク
デバッグを体系化すると、4つのステップに落ち着く。
Step 1: Reproduce（再現）
エラーを一貫して再現できる最小条件を特定する
Step 2: Isolate（分離） エラーの発生箇所を絞り込み、関係ない要因を排除する
Step 3: Fix（修正） 根本原因に対して修正を適用する
Step 4: Validate（検証） 修正が正しく機能し、他の部分を壊していないことを確認する
Claudeは「とりあえず直してみる」アプローチに傾きやすく、Step 1とStep 2をショートカットしようとする傾向がある。これを防ぐには、明示的に指示する必要がある。
「このエラーを修正する前に、まず根本原因を特定して。
症状ではなく原因に対してのみ修正案を提示して。
修正は私が承認するまで実行しないで」
分析深度を上げたい場合は「Think ultra hard」が有効だ。
「Think ultra hard about what's actually causing this error.
Consider: timing issues, state management, dependency versions,
environment differences. Find the actual root cause.」
（訳：このエラーの実際の原因について深く考えてください。タイミング問題・状態管理・依存関係のバージョン・環境の違いを考慮し、本当の根本原因を見つけてください）
複数の実践者が確認しているプロンプトパターンで、分析が表面的で終わりがちな場面で使いやすい。
/debugスキルと診断コマンドのフル活用
/debug：セッション内のトラブルシュート
`/debug` はClaude Codeに標準搭載されているバンドルスキルだ。セッションのデバッグログ（会話履歴・ツール使用・エラー情報）を元に、何が問題になっているかを分析して報告する。
こういうときに使いやすい。「Claudeが同じ間違いを繰り返している」「長いセッションで突然挙動がおかしくなった」「なぜClaudeがそのアクションを選んだか理解できない」。
/doctorとの使い分け
/doctor → 環境・依存関係・設定ファイルの問題をチェック
/debug → 現在のセッション内のデバッグログを読んで分析
「Claude Codeが動かない」は環境問題か、セッション問題かで対応が変わる。`/doctor` でバージョン互換性・CLAUDE.mdの構文・MCPサーバーの接続状態を診断し、問題なければ `/debug` でセッション内を分析する。
/rewind：間違えた修正を巻き戻す
Claudeがアクションを実行するたびに自動でチェックポイントが作成される。`/rewind`（またはEscキー2回）で一覧が表示され、会話・コード・またはその両方を任意の時点に戻せる。「Claudeが間違った修正を重ねてしまった」場合に使う。
/insights：摩擦ポイントの発見
`/insights` は過去30日間のセッションを解析し、インタラクティブなHTMLレポートを生成する。摩擦ポイント分析（Claudeが意図を誤解したパターン・多回修正が必要だったタスク）とCLAUDE.md提案（繰り返し伝えている指示をコピペできる形式で出力）が含まれる。ローカルのセッションログのみを使用し、外部にデータは送信されない。
視覚的デバッグ：スクリーンショットをClaudeに渡す
テキストで説明が難しいUIバグ・レイアウト崩れ・レンダリング問題は、スクリーンショットを直接渡すのが最速だ。
# Macでスクリーンショット → Claude Codeに貼り付け
Cmd+Shift+4 でスクリーンショット → チャットに直接ペースト
より高度な方法としてMCPを使った自動スクリーンショットがある。
# Playwright MCPを使った自動スクリーンショット
「Playwright MCPでhttp://localhost:3000を開いて、
現在の表示状態をスクリーンショットで確認して」
# Chrome DevTools MCPを使ったコンソールエラー取得 「Chrome DevTools MCPでコンソールエラーを確認して、 エラーの内容を分析して原因を特定して」
CSSレイアウトのズレ・非同期処理のタイミング問題・レスポンシブデザインの崩れといった「テキストで説明より一目瞭然」な問題に特に有効だ。
MCPを使ったデバッグ強化
Sentry MCP：本番エラーの直接分析
「Sentry MCPで直近24時間のエラーを確認して、
最も影響度が高い問題を特定して修正案を提示して」
AnthropicのSecurity EngineeringチームはスタックトレースとドキュメントをClaude Codeに投入することでデバッグ速度を3倍高速化した。MCPで本番ログに直接アクセスさせると、この効果がさらに増幅する。
別の実践例では、Kubernetes環境でのIP枯渇障害（Pod突然スケジュール不可）を手動調査6時間から2時間に短縮したケースがある（複数のkubectl logsを横断投入し、CNI設定バグを特定）。いずれもコミュニティから報告されている参考値だが、「複数の情報源を横断投入して根本原因を特定する」というパターンは一貫して有効だ。
自己修正ループ：同じエラーを二度起こさせない
個人的に一番効いたのが「デバッグ結果をCLAUDE.mdに反映するループ」だ。
エラー発生
↓
根本原因を特定（Think ultra hard）
↓
「このエラーを防ぐルールをCLAUDE.mdに追加して」
↓
CLAUDE.md更新（次回セッションから自動適用）
HooksのPostToolUseでエラーを自動捕捉することもできる。
hooks:
PostToolUse:
- matcher: "Bash"
hooks:
- type: command
command: |
if [ $EXIT_CODE -ne 0 ]; then
echo "ERROR: $TOOL_OUTPUT" >> ~/.claude/error_log.txt
fi
PreToolUseで危険なパターンを検知してVIOLATIONで止める設計もある。「同じ間違いが繰り返される」と感じたら、それはCLAUDE.mdへ移す候補だ。
デバッグセッション設計のコツ
新しいセッションでデバッグを始める: 長いセッションでバグが発生した場合、同じセッションでのデバッグはコンテキスト汚染のリスクがある。コミュニティの実践報告では45分以上のセッションの約70%がコンテキスト上限問題を経験するとされている（参考値）。新しいセッションで最小再現コードだけを渡してデバッグさせる方が、整合性のある分析が得られる。
デバッグ依頼テンプレートを用意する: CLAUDE.mdにこのテンプレートを書いておくと、毎回の依頼が標準化される。
## デバッグ依頼テンプレート
エラーメッセージ: [貼り付け] 発生条件: [どういう操作をしたとき] 期待する動作: [本来こうなるべき] 実際の動作: [こうなっている] 試したこと: [既に試みた解決策]
「根本原因を特定して。修正前に分析結果を報告して。 修正の承認を待って」
ビフォーアフター
Before（表面的なデバッグ）
エラー発生 → 「Claudeに直して」 → 試行錯誤で一時的に解決 → 数分後に同じエラーが再発 → セッションが長くなりコンテキストが汚染 → Claudeの提案が整合性を失う。
After（体系的なデバッグサイクル）
新セッション＋最小再現コードを渡す → 「Think ultra hard」で根本原因を特定 → Reproduce→Isolate→Fix→Validateを踏む → 視覚的デバッグ/MCPログ分析/`/doctor`で補強 → 修正後、CLAUDE.mdに「次回防止ルール」を追加 → 同じエラーは二度起きない。
まとめ：今日からできること
- 今すぐ（5分）: 現在進行中のプロジェクトで `/doctor` を実行し、環境問題がないか確認する
- 今日中: 次にエラーが発生したら「Think ultra hard about the root cause」プロンプトを試す
- 今週: デバッグ依頼テンプレートをCLAUDE.mdに追加し、依頼の質を標準化する
- チーム展開: Playwright MCP＋Chrome DevTools MCPを`.mcp.json`に追加し、UIデバッグを自動化する
「エラーを直す」から「同じエラーが二度起きない仕組みを作る」——この発想の転換がClaude Codeのデバッグで最も大きな差を生むと感じている。
コメント