Debugging

デバッグ・バグ調査

目的

当てずっぽうの変更を排除し、観察→仮説→検証の科学的サイクルで根本原因を特定する。 直したことを再現手順で確認し、回帰テストで再発を防ぐことを最終ゴールとする。

使うタイミング

• 「エラーが出る・テストが落ちる・画面がおかしい」など不具合を調査するとき
• 本番障害の根本原因を調査するとき(復旧後 → [[monitoring-operations]] と連携)
• コードを変更したら意図しない動作が起きたとき
• 原因不明のまま修正をクローズしそうなとき

進め方

1. 再現手順を確立する まず「再現できる状態」を作る。再現できないバグは直せない。 再現条件(環境・データ・操作・タイミング・OS/ブラウザ)を文書化し、最小化する。 本番のみ発生する場合は環境差分(設定・DB・外部サービス接続)を洗い出す。

2. 最近変えたものを最初に疑う 直近のコミット・依存ライブラリの更新・設定変更・デプロイ・インフラ変更を確認する。 git log --oneline -20、git diff HEAD~1 で変更差分を確認する。 git bisect で問題を含むコミットを二分探索で特定する。

3. 観察手段を増やす

   • ログ追加: 仮説の分岐ポイントに console.log / logger.debug を挿入する
   • デバッガ: ブレークポイントでステップ実行し変数の実値を確認する
   • エラーメッセージを最後まで読む: スタックトレースの先頭だけでなく根本のエラーを見る
   • 最小再現コードを作る: 関係ない要素を取り除き問題を孤立させる

4. 仮説を立てて1つずつ検証する 「〇〇が原因なら△△になるはず」という形で仮説を書き出す。 一度に変更するのは1箇所だけ。複数同時に変えると何が効いたか分からない。 仮説が外れたら元に戻してから次の仮説へ進む。

5. 二分探索で絞り込む コード範囲が広い場合は半分ずつ切り分ける。 「この行より前では正常、この行より後で異常」を確定させる。 データ起因の疑いがある場合はデータを半分に絞って再現するか確認する。

6. 根本原因を特定し修正する 症状ではなく根本原因を直す。症状を塞いだだけでは別の場所で再発する。 修正後、最初に確立した再現手順で直ったことを確認する。

7. 回帰テストを書いて終わりにする 修正内容に対応する[[testing]]の単体/結合テストを書く。 「このバグが再発したらテストが落ちる」状態にして初めてクローズ。

8. 本番障害の場合は復旧優先 影響範囲の把握とロールバック/フィーチャーフラグによる復旧を優先する。 根本原因調査は復旧後に行う([[monitoring-operations]] 参照)。

思い込みを疑うチェックリスト

• そのコードが本当に実行されているか(ログを入れて確認したか)
• 正しい環境・正しいブランチを見ているか
• キャッシュ(ブラウザ/CDN/ビルドキャッシュ/DBクエリキャッシュ)が効いていないか
• データは想定どおりの型・値・件数か(nullや空文字を見逃していないか)
• エラーの発生箇所は本当にそこか(根本原因は上流の別処理かもしれない)
• 依存ライブラリのバージョンが変わっていないか(package-lock.json等を確認)
• 環境変数・設定ファイルが正しく読み込まれているか
• 非同期処理の完了を待っているか(race condition / タイミング問題)
• エラーが握り潰されていないか(catch節で何もしていないコードがないか)

成果物テンプレート

## バグ調査メモ

### 事象
<!-- 何がどうなっているか。スクリーンショット/エラーメッセージをそのまま貼る -->

### 再現手順
1. 
2. 
3. 
期待結果:
実際の結果:

### 環境
- OS/ブラウザ:
- バージョン/ブランチ:
- 再現率: □ 100%  □ 高(80%〜)  □ 低(〜20%)  □ 特定条件のみ

### 仮説と検証履歴
| # | 仮説 | 検証方法 | 結果 |
|---|------|----------|------|
| 1 | 〇〇が原因では | ログ追加/コメントアウト | ✗ 外れ / ✓ 当たり |
| 2 | | | |

### 根本原因
<!-- 特定した根本原因を1〜2文で -->

### 修正内容
- ファイル: 
- 変更概要: 

### 回帰テスト
- テストファイル: 
- テスト名: 

### 再発防止
<!-- コード修正以外に必要な対策(ドキュメント追記・監視追加など) -->

チェックリスト

• 再現手順が文書化されているか
• 修正前に再現を確認したか
• 一度に変更したのは1箇所だけか
• 修正後に再現手順で直ったことを確認したか
• 根本原因が特定できているか(症状だけ塞いでいないか)
• 回帰テストを書いたか
• 調査メモに仮説と検証結果の履歴が残っているか
• 本番障害の場合は復旧が完了した後に根本原因調査を始めたか

アンチパターン

アンチパターン	何が問題か	対処
当てずっぽう変更→「動いたから終わり」	根本原因が不明のまま残り、別の場所で再発する	「なぜ直ったか」を説明できるまで調査する
再現確認せずにクローズ	本当に直っているか分からない	修正後に必ず再現手順を実行して確認する
複数箇所を同時に変更する	何が効いたか特定できなくなる	1仮説=1変更を徹底し、外れたら元に戻す
エラーメッセージでググる前に悩み続ける	既知の問題に気づかず時間を無駄にする	まずエラーメッセージをそのまま検索する
症状だけ塞ぐ	null チェック追加などで表面を隠し根本は残る	なぜnullになるのかまで追う
スタックトレースの先頭だけ読む	ラップされた例外に隠れた根本原因を見逃す	Caused by: など最深部まで読む
15分考えても進まないのに続ける	思い込みループにはまる	ラバーダック(言語化)して別エージェントや同僚に相談する

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

モデル	役割の目安
司令塔	仮説の立案と検証計画の設計・調査メモのレビュー・根本原因の最終判断・修正方針の決定
Opus相当	難解なバグ(非同期race condition・メモリリーク・分散システムの整合性崩れ)の根本原因分析
Sonnet相当	最小再現コードの作成・修正実装・回帰テスト実装・コード差分の調査
Haiku相当	ログ収集・関連コードの探索・エラーメッセージの検索・変更履歴の確認

関連スキル

• [[testing]] — 回帰テストの実装・テスト戦略
• [[monitoring-operations]] — 本番障害時の復旧フロー・アラート設計
• [[code-review]] — 修正コードのレビュー観点
• [[refactoring]] — バグの温床となる複雑なコードの整理
• [[orchestration]] — モデル委譲の共通原則
• [[cicd-deployment]] — ビルド/デプロイ起因のバグの調査
• [[git-workflow]] — git bisect によるコミット特定・ブランチ管理