定義と結論
仮説駆動デバッグとは、観察できた事実から原因候補を立て、その候補を判定できる確認を一つずつ行う調査方法です。コードを眺めて「怪しそうな場所」を直し続ける方法ではありません。
基本単位は「事実・仮説・確認・判定」の4つです。
事実: 保存APIが400を返し、レスポンスに email is required とある
仮説: フォームのemailがRequest bodyへ入っていない
確認: DevToolsのNetworkで送信Payloadを見る
判定: emailがなければ送信側、あれば受信後の処理を調べる
デバッグの進展は、変更した回数ではなく、証拠によって原因候補を減らした回数で測ります。 最短で直すことより、なぜ直ったかを説明でき、同じ問題を再現・予防できる状態を目指します。
なぜ必要なのか
不具合が起きると、人は直前に見たコードや過去に遭遇した原因を重視しがちです。しかし、画面に値が出ない問題でも、原因はDOM更新、API応答、認証、キャッシュ、データベースなど複数の層にあります。根拠なく複数箇所を変えると、次の問題が起きます。
- どの変更が効いたのか分からない
- 一時的に症状が消えただけでも修正済みと誤認する
- 新しい不具合を混ぜ、元の原因を見えにくくする
- 他の人が調査を引き継げない
- 不要な修正が残り、将来の保守コストになる
仮説を先に書けば、確認結果が予想と違っても情報が残ります。「仮説が外れた」は失敗ではありません。たとえばPayloadにemailが存在すると分かれば、フォーム入力からHTTP送信までの範囲を候補から外せます。
登場人物と対象
この方法は開発者だけのものではありません。利用者は症状と再現条件を伝え、サポート担当は影響範囲を整理し、開発者はクライアント・ネットワーク・サーバーの証拠を集めます。レビュー担当者は修正が仮説と対応しているか、テストが再発を検知できるかを確認します。
対象は、例外が出る不具合だけではありません。表示崩れ、処理の遅さ、環境ごとの差、テストの失敗、「たまに起きる」問題にも使えます。ただし本番障害で利用者への影響が続いている場合は、原因究明よりロールバックや機能停止などの影響軽減を優先します。
仮説駆動デバッグの流れ
1. 症状を再現可能な文にする
「保存できない」では情報が足りません。「ログイン済み利用者がプロフィール画面でemailを空にして保存すると、POST /api/profile が400を返す」のように、前提・操作・期待値・実際の結果を分けます。毎回起きるか、特定ブラウザやデータだけかも記録します。
2. 観察事実を集める
画面のメッセージ、Console、Network、サーバーログ、テスト結果を確認します。「APIが壊れている」は解釈ですが、「POSTが400で、応答本文がこの内容」は事実です。時刻、URL、ステータスコード、入力値など、後から第三者が確認できる形にします。
3. 処理を境界で分ける
Webアプリなら、入力、イベント処理、リクエスト生成、ネットワーク、API、業務ロジック、DB、レスポンス、描画という境界があります。最初から関数を一行ずつ追うのではなく、どの境界までは正常かを調べます。
「どこが壊れたか」より先に、「どこまでは正しいか」を確定すると調査範囲が急速に狭まります。
4. 判定可能な仮説を一つ選ぶ
良い仮説は具体的で、反証できます。「JavaScriptがおかしい」では広すぎます。「submit時にFormDataへemailが追加されていない」ならPayloadを見るだけで判定できます。候補が複数ある場合は、確認コストが低く、結果によって大きく枝分かれするものから試します。
5. 最小の確認を行う
まず観測で判定し、必要な場合だけ最小変更を加えます。ログを1行足す、失敗テストを1件作る、固定入力で関数を呼ぶ、といった方法です。フォーム名、API URL、バリデーションを同時に変更してはいけません。
6. 結果を記録して更新する
仮説と一致したか、何が分かったか、次にどの層を見るかを短く残します。仮説が正しければ原因をさらに細かくし、外れたら除外できた範囲から次の仮説を作ります。修正後は元の再現手順と周辺ケースを再確認します。
主要な調査パターン
| パターン | 使いどころ | 確認例 |
|---|---|---|
| 境界を追う | 入力から出力まで複数層を通る | Payload、API応答、DB結果を順に見る |
| 二分探索 | 正常地点と異常地点の間が長い | 処理の中間値を確認して範囲を半分にする |
| 差分比較 | ある環境・入力だけ失敗する | 成功時と失敗時の設定、要求、データを比較 |
| 最小再現 | 要因が多く相互作用する | 最小の入力・依存関係で症状を再現する |
| 直前変更の確認 | リリース後から発生した | デプロイ、設定、依存更新の差分を見る |
直前変更は有力な手掛かりですが、原因と決めつけてはいけません。以前から潜んでいた問題がデータ量や外部サービスの変化で表面化する場合もあります。
具体例：保存APIが400になる
最初の事実が「ボタンを押すと400」だけなら、まずNetworkを見ます。Payloadにemailがなければ、入力要素のname、状態管理、送信処理が候補です。emailがあれば、サーバーがどのフィールド名を期待するか、JSONを正しく解析できたかへ進みます。
ここで入力名を直す前に、成功する別フィールドと比較します。emailAddressを送ってサーバーがemailを読むという契約差なら、仮説は「クライアントとAPIでフィールド名が一致していない」です。確認はAPI仕様、実際のPayload、受信直後の値の3点です。修正後はemailあり・なしの両方をテストし、単に必須チェックを消して通す対応は避けます。
よくある誤解
仮説は当てなければならない
仮説は推測を正当化する言葉ではなく、調査を進めるための暫定説明です。外れた結果にも除外情報があります。重要なのは、外れた仮説を証拠なしに復活させないことです。
ログを大量に出せば分かる
量より、境界と相関が重要です。リクエストID、処理段階、結果、時刻がなければ大量のログでも追跡できません。パスワード、トークン、Cookie、個人情報を出力してはいけません。
エラーメッセージが原因を示す
メッセージは失敗を検知した場所を示すことが多く、根本原因とは限りません。Cannot read properties of undefinedなら、読む行だけでなく、値がどこでundefinedになったかを上流へ追います。
とりあえず再起動で直れば完了
再起動で状態が消えれば復旧には役立ちますが、原因説明にはなりません。再発条件、影響、再起動前後の証拠を残せないと同じ障害を繰り返します。
注意とベストプラクティス
- 調査開始前に現在の差分を把握し、無関係な変更を混ぜない
- 一つの確認で複数の候補を分けられる質問を優先する
- 正常系と失敗系を同じ観測点で比較する
- 時刻、環境、入力、結果を調査メモに残す
- 本番データの変更は避け、必要なら承認と復旧手順を用意する
- 修正後に失敗を再現するテストを追加する
「修正案を試す」と「原因を確認する」は別の行為です。 修正案が症状を隠す場合もあるため、変更前の証拠を確保し、変更と結果を一対一に対応させます。
デバッグ完了の確認方法
完了条件は「今は動く」だけではありません。元の手順で再現しない、失敗を説明する仮説が証拠と一致する、修正がその原因に対応する、周辺の正常系を壊していない、再発を検知できるテストや監視がある、という順で確認します。
調査メモを見ずに、第三者へ「どの事実から何を疑い、何を確認し、なぜこの修正になったか」を短く説明できるかも有効です。説明に飛躍があれば、まだ推測が残っています。
まとめ
仮説駆動デバッグの中心は、事実と推測を分け、判定できる仮説を作り、最小の確認を一つずつ行うことです。外れた仮説も調査範囲を狭める成果になります。
速いデバッグとは、手を速く動かすことではなく、次に見るべき場所を証拠で選び続けることです。
