diagnosing-bugs

バグの診断

修正する前に、観測された障害のメカニズムを特定します。このスキルが担当するのは診断であり、本番環境の修正ではありません。

まずは軽く調べます。エラー、スタックトレース、既存の再現手順または取得済みの成果物、関連する最近の変更を確認します。その証拠だけでメカニズムを特定できる場合は、手順を不必要に長くせず、そのまま報告します。不確実性に応じてのみ調査を深めます。

症状の範囲を定める

正確に観測された症状、影響を受けたユーザーまたはシステムの経路、リビジョンと環境、既知のトリガー、再現性または観測された発生率、重要な制約を記録します。観測した事実と、報告または推測された内容を区別します。

コマンド、メモ、返却する証拠には、秘密情報、個人データ、認証情報、無関係なペイロードを含めないでください。許可されている場合に限り、生の成果物をローカルに保持し、結果の裏付けに必要な、サニタイズ済みの最小限の証拠のみを提示します。

診断の手掛かりを確立する

利用可能な中で、症状に最も忠実かつ範囲の狭い証拠取得方法を選びます。

• 障害と同じ対象領域で実行できる再現手順
• ログ、トレース、プロファイル、デバッガー、一時的な計測による実行時の直接観測、または
• 出所とリビジョンを特定できる、トレース、プロファイル、コアダンプ、HAR、構造化ログなどの既存の固定成果物

症状の意味を保てる場合は、明確で、繰り返し可能で、妥当な速度で失敗を再現できる手順を優先します。断続的な障害では、基準となる発生率を測定し、障害の意味を変えずに可観測性または反復回数を高めます。再現ループを確保したと主張するだけのために、忠実度の低いモックを作成しないでください。

固定成果物の場合は、関連する時間範囲または経路を絞り込み、観測結果を一致するソースとリビジョンに対応付けます。重要な別の可能性を判別するのに役立つ場合に限り、比較用の成果物を探します。信頼できる成果物があれば、障害をライブ環境で再現しなくてもメカニズムを特定できる場合があります。

原因を判別するために必要な場合に限り、一時的なローカル計測または破棄可能なハーネスを使用できます。固有のタグを付け、明示的な権限なしに本番システムへ重大な変更を加えないようにし、返却前に削除します。

忠実な手掛かりを得られない場合は、不足している成果物、アクセス権、環境、権限、または観測能力を正確に示し、Inconclusive とします。

メカニズムを判別する

仮説の範囲を絞る場合に限り、症状を保ったまま、入力、依存関係、タイミング条件、プロセス境界、または状態の次元を一度に一つずつ取り除きます。さらに絞ると忠実度が下がる場合、または判断が変わらなくなる場合は、そこで止めます。

現在の証拠で裏付けられる仮説のみを立てます。可能性のある原因ごとに、重要な別の原因と区別できる観測結果を明示し、プローブを一つ実行するか、変数を一度に一つだけ変更します。障害に応じて、正常時と障害時の比較、履歴の確認または二分探索、境界の計測、依存関係の差し替え、並行処理の制御、トレースまたはプロファイルの比較などが有効なプローブになります。

仮説が実際に独立しており、変更可能な状態を共有しない場合は、読み取り専用の並行調査担当者を任意で使えます。1 人の責任者が、実際の証拠に照らして各担当者の主張を突き合わせる必要があります。デフォルトで調査を分散しないでください。

証拠が、提案したメカニズムと重要な別の可能性を区別できる場合に限り、Diagnosed とします。もっともらしい説明、相関関係、症状の消失、再起動の成功は、根本原因ではありません。

結論とクリーンアップ

一意にタグ付けされた計測機器と使い捨ての診断用成果物を削除し、調査で使用した状態を元に戻したうえで、承認済みのソース成果物とサニタイズ済みの証拠のみを保持します。このスキルの実行中は、コミット、ADR や計画の作成、作業の割り振り、修正としての本番コードの編集を行わないでください。

診断結果を次のいずれか一つに確定します。

• Diagnosed：症状、証拠、根本原因、原因を特定する観察結果を示します。リビジョンと環境、正確な再現手順と結果、再現性または測定された発生率、忠実度を保った最小シナリオまたは成果物、検証済みまたは否定された仮説、証拠の限界、重要な場合に限り忠実な回帰テストの接点を含めます。
• Inconclusive：症状、入手可能な証拠、正確な阻害要因、範囲を限定した最小の次のアクションを示します。リビジョンと環境、試行内容と結果、否定された仮説、重要な場合に限り残る可能性を含めます。残る可能性はすべて仮説として明示し、Root cause: not established. と記載します。

診断が割り当ての全体である場合は、その結果を返します。修正がすでに承認されている場合は、編集前に結果を記録し、呼び出し元の実装契約に従って同じ担当者として作業を続け、そのパスの最終引き継ぎに診断結果を含めます。修正には strategic-programming を使用し、忠実度を保った保守対象の接点である場合に限り、再現手順を回帰テストに変換して、該当するプロジェクトのゲートを実行します。

完了条件

原因を特定する証拠によって障害のメカニズムが確立されているか、正確な作業再開条件を明示したうえで、調査を誠実に終了しています。観察と推論を分け、機密データを漏らさず、一時的な変更を削除し、診断を修正と取り違えていません。