systematic-debugging

体系的なデバッグ

使用する場面

• バグ、エラー、例外、クラッシュの調査が必要な場合
• 「動作しない」ものがあり、原因が不明な場合
• テストが失敗していて、その理由が明らかでない場合
• どの言語やフレームワークでも、予期しない動作のトラブルシューティングが必要な場合

基本的なワークフロー

次の5つのフェーズを順番に実施します。切り分けと追跡が完了する前に、修正に進まないでください。

フェーズ 1：再現

まず、ほかの作業を始める前に、バグを確実に発生させる方法を確立します。

1. エラーメッセージ、スタックトレース、ログをすべて読み、正確な文言、行番号、エラーコードを記録します
2. 問題を安定して発生させる最小限の再現ケースを作成します
3. 失敗を引き起こす正確な手順、入力、環境を記録します

チェックポイント： 必要なときにバグを発生させられますか？発生が不定期な場合は、次に進む前にさらにデータを収集します。

フェーズ 2：切り分け

失敗の発生箇所を絞り込みます。

1. 二分探索を使って、失敗しているコンポーネントを特定します。システムの半分を無効化するか、スタブに置き換えます
2. git log --oneline -20 と git diff を使って、既知の正常な状態からの最近の変更を確認します
3. 対象を絞ったログを追加するか、デバッガーを使って重要な境界での状態を観察します

# Find which commit introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Git will checkout midpoints — test each one and mark good/bad

チェックポイント： バグの原因が特定の関数、モジュール、またはデータフローまで追跡されています。

フェーズ 3：根本原因を追跡

失敗が起きる「場所」だけでなく、その「理由」を理解します。

1. エントリーポイントから失敗箇所まで、コードパス全体を読みます
2. 前提条件を確認します。各関数が想定しているものと、実際に受け取っているものは何ですか？
3. データフローを逆方向にたどり、不正な値がどこで発生するかを調べます
4. アサーションや出力文を追加して仮説を検証し、証拠を確認します

# Example: verify assumptions about incoming data
def process_order(order):
    assert order.status == "pending", f"Expected pending, got {order.status}"
    assert order.items, "Order has no items"
    # ... rest of processing

チェックポイント： 発生のきっかけから症状に至る因果関係が、ログ、アサーション、デバッガーの出力などの証拠とともに説明されています。

フェーズ 4：根本原因を修正

症状だけではなく、実際の原因に対処する、的を絞った修正を適用します。

1. 下流の影響ではなく、根本原因を修正します
2. 修正は最小限にとどめ、必要な箇所だけを変更します
3. 根本的な問題を覆い隠す「その場しのぎ」の修正は避けます（例：クラッシュする理由を直さず、クラッシュの周囲に try/except を追加する）

フェーズ 5：検証

修正が機能し、リグレッションを引き起こしていないことを確認します。

1. フェーズ 1 の再現ケースを実行し、バグが解消されていることを確認します
2. リグレッションを確認するため、テストスイート全体を実行します
3. 修正に関連するエッジケースをテストします
4. バグに対応するテストがなかった場合は、そのバグを検出できるテストを追加します

チェックポイント： 再現ケースが成功し、テストスイートがすべて成功しており、このバグを対象とする新しいテストが追加されています。

避けるべき主なアンチパターン

• 手当たり次第のデバッグ：うまくいくことを期待して、無作為に変更を加える
• 修正して祈る：原因を理解せずに修正を適用する
• 再現を省略する：バグを発生させられることを確認せずに、コード変更に進む
• 症状の修正：エラーを引き起こす原因を修正せず、try/catch でエラーを包む

全項目については anti-patterns.md を参照してください。

関連スキル

• root-cause-tracing：コールスタックを深く追跡する手法。フェーズ 2 の後、バグが深い実行チェーンにある場合に使用します
• verification-before-completion：必須の検証ゲート。修正が完了したとする前にフェーズ 5 を徹底します

詳細な参考資料

• workflow.md：判断ツリーを含む、フェーズごとの詳しい手順
• examples.md：さまざまな言語でのデバッグ例
• troubleshooting.md：よくあるデバッグの状況と解決策
• anti-patterns.md：避けるべきパターンとその見分け方