バグの直し方:報告を読むところから閉じるところまでの 6 ステップ

バグを直すとは、再現する不具合を再現しない状態にし、それが戻らない証拠を残すことです。 前半は「コードを変える」、後半は「きちんと閉じる」。多くのチームは前半だけをやるので、同じ問題が 3 か月後に別の入口から戻ってきます。修正の質は、変更がどれだけ巧みかでは測れません。次の回帰テスト、次にコードを引き継ぐ人、そして 3 か月後のあなたが、記録だけで「本当に消えた」と判断できるかで測ります。 本記事は「どう直すか、どう検証するか、どう閉じるか」だけを扱います。「どれを先に直すか」はトリアージの領域です(不具合トリアージのガイド)。そもそも直せる報告の書き方は不具合報告に含めるべき内容にあります。

6 ステップのループ

各ステップには最低限必要な証拠があります。満たせないなら、次へ進むのではなく 1 つ戻る——これが本記事で最も実用的なルールです。
ステップ やること 最低限の証拠 満たせない場合
1 読む 着手できる報告か判断する ページ URL、環境(ブラウザ / OS / バージョン)、期待と実際 差し戻す。推測しない
2 再現 自分の手元で 1 回起こす 確定した再現 1 回、または明示した「再現不可」の結論 試した条件を記録し、保留。閉じない
3 特定 どの層の問題か突き止める エラー原文 1 行、失敗リクエスト 1 件、または二分探索の結論 変更を止め、観測手段を足す
4 修正 最小の変更で根本原因を除く 1 変更 = 1 原因 コミットを分ける
5 検証 直ったこと、他を壊していないことを証明する 同じ経路 + 境界 + 回帰マトリクス 「たぶん大丈夫」は検証ではない
6 閉じる 次の人が読めるようにする 根本原因 1 行 + 証拠へのリンク 「修正済み」だけでは閉じたことにならない

ステップ 1:報告を読み、着手できるか判断する

着手できる報告には最低 3 つあります。どこで、どんな環境で、期待と実際がどう違うか。 どれか欠けたら、正しい行動は差し戻しです。コードを開いて探し始めることではありません。 「とりあえず探す」のコストは大きく過小評価されています。開発者が 40 分かけて推測した「あのページ」のうち、かなりの割合が報告者が指したページではありません。差し戻し 1 回のコストは 2 分です。

ステップ 2:再現する、あるいは「再現できない」と明言する

再現は分水嶺です。安定して再現する不具合は、特定は時間の問題です。再現しない不具合は、どんな変更も賭けになります。 再現時には 3 つを固定しないと、同じ問題を再現したことになりません。
  • データ状態:どのアカウントか、キャッシュが絡むか、localStorage に古いデータが残っていないか
  • ビルドのバージョン:フロントのバンドル、バックのコミット、有効な feature flag
  • 操作の順序:読み込み直後にクリックしたのか、数秒後か、タブを切り替えた後か、回線が遅いときか
  • 本当に再現しない場合は、閉じるのではなく「再現不可」として 3 つの問いを添えて記録します。
    • どのページ、どの入口から来ましたか(元の URL にはパラメータが付いていることが多い)
    • 特定のアカウント / ロール / 権限に紐づきますか
    • 発生した時刻はいつですか(ログやデプロイの時刻と合えば手がかりになります)

    ステップ 3:特定——まず層を決める

    遅い修正は難しい問題ではなく、誤った層で探している問題であることがほとんどです。3 つの動作で 1 つの層に絞ります。
    動作 見るもの 排除できるもの
    コンソール エラー原文とスタック 「純粋にスタイル / 純粋にデータ」の問題
    ネットワークパネル 4xx / 5xx の有無、リクエストとレスポンスの中身の整合 「フロントが送っていない」と「バックが誤ったものを返した」の切り分け
    二分探索 / ロールバック 最後に正常だったバージョンやコミット 「昔からこうだった」という誤解
    エラーの読み方はログレベルの説明とプログラミングにおけるエラーの種類。コンソールの開き方はブラウザのコンソールを開く。非開発者がまず自分で見たい場合は非開発者向けブラウザ DevTools。 判断の順序は具体的に:API が 500 → バック。API は 200 だがフィールドが違う → 契約。API が呼ばれていない → フロントのロジックかバリデーション。API は正常で画面が違う → 描画。 この 4 行で Web チームの大半はカバーできます。

    ステップ 4:最小の変更で直す

    「最小の変更」は慎重さではなく検証可能性です。1 つの PR でバグ修正・リファクタ・依存の更新を同時に行うと、次に問題が出たときどれが原因か言えません。するとステップ 5 は通せません。 2 つのルール。
    • 1 コミット = 1 原因。 直している途中で別の問題を見つけたら、別チケットにする。
    • リファクタには専用の時間を。 修正中のリファクタは「既知のリスク」と「未知のリスク」を混ぜます。

    ステップ 5:検証——「直った」ではなく「隠していない」ことを証明する

    ここが本記事と一般的な「バグの直し方」記事との最大の違いです。次の 4 つは不具合を消しますが、問題は残ります。
    やり方 見た目 実際
    空の try / catch エラーが消える 後続処理が静かに失敗し、データが誤って書き込まれる
    バリデーションを緩める エラーが出なくなる 汚いデータが DB に入り、数か月後に発覚する
    入口を隠す ユーザーが押せなくなる 需要は残り、別の経路で来る。挙動が食い違う
    二度と戻さないフラグ 症状が出なくなる フラグ自体が誰も消せないコードになる
    判断基準は 1 つだけ。ユーザーはやりたかったことを今できるか。 「エラーが消えたか」ではありません。 検証は 3 つ。
  • 元の経路をもう一度通す — 報告に書かれた道を最初から最後まで
  • 境界をもう一度試す — 空値、極端に長いテキスト、絵文字、タイムゾーン、金額の小数、権限のないアカウント。この 6 つが再発の巣です
  • 回帰マトリクスを回す — この変更が触れた可能性のある既存機能。回帰テストの回し方を参照
  • ステップ 6:根本原因 1 行を書いて閉じる

    「修正済み」だけで閉じるのは、コストを次の人に押し付けることです。完全な根本原因のメモは 3 部構成です。
    text
    根本原因:注文確定時、リクエスト送信前にフォームを空にしていたため、
              送信失敗でフォームが空のまま残った。再試行で空データを送り、
              500 が返り、静かな catch が握りつぶしていた。
    修正:先に送信し、成功時に空にする。静かな catch を削除し、
          エラーメッセージを表示するよう変更。
    検証:Chrome 141 / macOS 14、ネットワークを切って 3 回再試行し、
          いずれも「送信に失敗しました。再試行してください」を表示し、
          フォーム内容は保持された。回帰:決済フロー、クーポン、住所帳。
    
    この 3 部は「なぜ壊れていたか」「何を変えたか」「どう証明したか」に答えます。diff より長生きします — 半年後、diff は書き換えられ、ファイルは分割され、モジュールは差し替わっても、このコメントは残ります。 証拠をチャットだけに置かないこと。スクリーンショット、録画、失敗リクエストは記録と一緒に残す必要があります。そうしないと 3 か月後に回帰が失敗したとき、「当時どうだったか」を辿ると切れた画像リンクに着きます。BugCapturer の拡張は送信時にコンソールエラー、失敗リクエスト、ページ URL、ブラウザとビューポートを一緒に持ち、共有リンクを生成します。チームプランではレポートが長期保存されます。理由は単純です——「元の報告が開ける」という事実を、3 か月後にも成立させるため。

    再現が失敗する 3 つの実際の原因

    「再現できない」は不具合管理のブラックホールです。運の問題であることは稀で、次の 3 つの差分のどれかです。 1. 環境の差分。 よくある 5 つ:ビルドのバージョン(ローカルは最新 main)、キャッシュ(ブラウザ、Service Worker、CDN)、feature flag、権限とロール、タイムゾーンと言語。やるべきはこの 5 つを 1 つずつ揃えることで、「もう一度試してみて」ではありません。 2. データの差分。 ユーザーのデータには 300 字のメモ、絵文字のニックネーム、null のミドルネーム、マイナスの金額が入っています。画面は「正常なデータ」では常に正しい。再現できる人は、たいていその具体レコードの ID を持っています。 3. タイミングの差分。 非同期の競合、遅延読み込み、デバウンス、外部コールバックの順序。速い回線では出ず遅い回線では必ず出る。開発機ではいつも正常です。手段は帯域制限と人工的な遅延で、ログを増やすことではありません。 再現できないときの正しい記録は、保留 + 試した条件の一覧 + 3 つの問い(入口 / アカウント / 時刻)。閉じるのが最悪の選択です。起きたという情報を失い、しかも必ずまた来ます。

    patch、hotfix、通常修正:3 つのテンポを混ぜない

    同じバグでも、影響範囲と緊急度で経路が決まります。難易度ではありません。
    通常修正 patch hotfix
    状況 主フローを止めない、版を待てる 範囲は小さいが早く出したい 本番の主フロー停止 / 金銭損失 / セキュリティ
    プロセス 通常のイテレーションとレビュー 次のマイナー版に同梱 通常プロセスを迂回し、後からレビュー
    必須の追加 回帰マトリクス 回帰マトリクス + 変更記録 回帰マトリクス + 変更記録 + 振り返り
    最も抜けやすい 境界の検証 影響ユーザーへの通知 表面だけ直して原因を直さない
    3 つのうち hotfix のリスクは速さではなく、終わった後に誰も振り返らないことです。暫定変更がコードに残り、回帰が追加されず、振り返りも書かれない。hotfix の後には最低 3 つ残してください——リリース記録 1 件、狙った回帰 1 回、「なぜ本番に漏れたか」の 1 行。リリース記録はバージョン更新記録にあります。

    チームの 5 つのルール

    持ち帰るのが 5 つだけなら:
  • 着手できない報告は差し戻す。推測しない。 差し戻し 2 分、推測 40 分。
  • 1 コミット = 1 原因。 混ぜた変更は検証もロールバックもできない。
  • 閉じるときは根本原因と証拠リンクを必ず書く。 半年後の誰かの 1 日を守る唯一のルール。
  • 「再現できない」は閉じる理由ではなく、保留する理由。
  • 回帰マトリクスを埋め戻さない修正は未完了。 抜けた 1 行が次の事故の入口です。
  • 不具合・要望・エラー・バグの境界は曖昧になりがちです(bug / defect / issue / error の違い)。「直ったことをどう顧客に伝えるか」は不具合報告を顧客と共有するへ。

    よくある質問

    バグ修正と新機能の優先順位はどう付ける? 影響範囲 × 頻度で決め、「声の大きさ」では決めません。深刻度 × 優先度のマトリクスはトリアージガイドにあります。ここで 1 点だけ補足します。並べ替えた後にスプリント途中で何度も割り込まないこと。 割り込みを繰り返すチームは、たいてい両方のトラックを終えられません。 複数のバグを 1 回の変更で直してよい? 同じ原因・同じ箇所のときだけです(1 つの原因が 3 つの症状を生むなら同じバグ)。原因の異なる不具合を 1 コミットに入れるとロールバックが不可能になります。本番で問題が出たとき、丸ごと戻すしかなくなります。 すべてのバグに単体テストは必要? 不要です。書く価値があるのは 3 種類——再発するもの(回帰の履歴がある)、分岐の多いロジック、データを計算するもの(金額・比率・日付)。表示のみ・文言のみの修正は回帰の目視で足ります。 直している途中で別の問題を見つけました。一緒に直す? いいえ。別チケットにしてください。混ぜるとステップ 5 の検証が無効になります。どの変更で問題が消えたのか言えなくなるからです。 本番のバグを直した後、ユーザーに通知すべき? 送信済みデータ、金額、注文状態に影響したなら、何を修復したかを添えて能動的に知らせます。短時間の利用不可で復旧済みなら、ステータス更新 1 回で足ります。バージョン更新記録に書いておけば、「記録はあるのか」と顧客に聞かれたときの答えにもなります。