バグを、失敗するテストで再現してから最小の修正で直す

## コードに触る前に、バグがどの部分の問題かを分ける 症状が現れたファイルではなく、観察できる影響から始める。有用な初期調査結果は、何が失敗し、誰または何が影響を受け、どのコンポーネントがその動作を担っているかを次の調査担当者に伝える。 ### 作業前に分類する - 不具合を、コア動作、システムまたは統合動作、ホスト環境の動作のいずれかに分類する。 - 症状を表示するコンポーネントと、失敗している動作を制御するコンポーネントを分けて考える。 - 現在のコンポーネントの外に原因があることを証拠が示す場合は、その動作を所有する境界へ作業を移す。 ### 証拠の範囲を定める 発生の引き金となる入力、初期状態、利用者が行った正確な操作、期待結果、実際の結果、関連する環境を記録する。事実と仮説は分けて列挙する。初期調査中は実装コードを編集しない。次の段階で、まず再現可能な失敗を確立しなければならない。 この分類は暫定的なものとする。後の証拠が分類と矛盾する場合はここへ戻り、責任範囲を修正し、実際にその動作を担う層へテストを移す。 ## 利用者に見える失敗を、失敗するテストで再現する 報告内容を、利用者の体験と一致する範囲で最も短く反復可能なシナリオにする。意味のある入力、状態、手順、目に見える結果は維持し、失敗に影響しない付随的な準備は省く。 ### 最も近く、信頼できるテスト層を選ぶ - 独立したロジックには、対象を絞った単体テストまたはコンポーネントテストを使う。 - 永続化、描画、通信、または複数コンポーネントが関与する場合は、統合テストまたはシステムテストを使う。 - 実際の操作、フォーカス、タイミング、画面遷移、または視覚的な状態に依存する場合は、ブラウザテストまたはエンドツーエンドテストを使う。 ソースコードを変更する前に回帰テストを書く。実行し、壊れた準備、古いアセット、不足したデータ、無関係なアサーションではなく、報告された理由で失敗することを確認する。実際に失敗するところを一度も確認していないテストは、不具合の証拠にならない。 動作を自動化できない場合は、その理由を記録し、決定的な手動手順、スクリーンショットの連続記録、トレース、測定結果など、反復可能で最も強い代替証拠を残す。失敗の証拠を信頼できる状態にするまで、実装コードは変更しない。 ## 動きが期待と最初にずれる所を探し、本当の原因を突き止める 失敗の再現が安定してから調査する。一度に複数箇所を変更せず、妥当な仮説を複数立て、対象を絞った観察で一つずつ検証する。 ### 最初の分岐点を追跡する 失敗する入力を、状態変化、境界、制御フローに沿って追跡する。成功するケースと失敗するケースを比較し、実際の動作が期待する動作から最初に分かれる地点を見つける。生成物、永続化された値、統合先からの応答、またはタイミングは、再現結果が関係を示す場合にだけ調べる。 各仮説について、どの証拠が裏付けまたは反証になるかを予測し、仮説を判別できる最小の確認を実行して結果を記録する。根本原因を、その後に生じた損傷や、不具合を観察しやすくするだけの条件と区別する。 原因の切り分け中は実装ロジックを変更しない。すべての仮説が否定された場合は再現工程へ戻り、その前提を確認し、分類を見直して、証拠に基づく新しい仮説を立てる。 ## 最小の修正で直し、テストを再発の見張りとして残す 根本原因を切り分けたら、意図した動作を回復するために必要な最小の範囲だけを変更する。外部仕様と無関係な動作を維持し、失敗ケースに不要な整理、再設計、リファクタリングは避ける。 最初に、元の失敗するテストを実行する。原因が取り除かれたために合格しなければならない。アサーションを弱めた、シナリオを省略した、テスト用データが不具合を通らなくなったことを合格理由にしてはならない。そのテストは恒久的な回帰防止策として残す。 次に、直接影響を受けるテスト群と、関連する静的検査、リンター、または型検査を実行する。変更が共有境界をまたぐ場合、または狭い範囲の証拠からより広い危険性が見つかった場合にだけ、対象を広いテスト群へ拡張する。新たな失敗はすべて証拠として扱い、実際の回帰なら修正し、提案した修正が不完全なら根本原因の切り分けへ戻る。 最終差分を見直し、意図しない編集、重複ロジック、弱められた検証、見落とした境界条件がないか確認する。この段階では、対象の動作と直接影響を受ける周辺の動作がすべて正常になった時だけ、修正完了とする。 ## 本番に近い環境で利用者と同じ手順をくり返し、直ったと確かめる 自動テストは必要だが、実際の利用経路の確認に代わるものではない。不具合を明らかにした意味のある入力と状態を同じように使い、代表的な実行環境で元の利用者向け手順を繰り返す。 利用者から見える境界で、修正前と修正後の結果を比較する。必要に応じて、利用者が最終的に依存する永続化結果、描画結果、発行されたイベント、統合先への受け渡し、または再構築された生成物も確認する。別の担当者が結論を検証できるよう、環境、手順、観察結果を記録する。 手動操作でまだ失敗する場合、自動テストの結果と異なる場合、または文書化されていない回避策が必要な場合は、不具合を解決済みと宣言してはならない。分類または再現工程へ戻り、見落とした条件をテストへ追加し、原因究明、修正、回帰確認、実地検証のループを繰り返す。 最後に、不具合の分類、確認済みの再現、根本原因、最小限の変更、回帰テストの範囲、直接影響を受ける検査、実際の利用手順での結果を、証拠に基づいて簡潔に報告する。不具合から繰り返し起こり得る構造的な一群が明らかになった場合にだけ、再利用可能な予防ルールを追加する。一度限りの詳細はテストと変更履歴に残す。