superior-debugging

優れたデバッグ

観測された障害を、根拠に裏付けられた原因の説明へと結び付け、必要十分な最小限の修正を行います。ユーザーの要望の範囲とリポジトリの既存アーキテクチャを保ちながら、証拠と推測を区別します。

障害を正確に定義する

コードを変更する前に、以下を明確にします。

• 観測された結果、期待される結果、およびその期待の根拠；
• 判明している最小の再現手順と、再現性の有無；
• 影響を受けるバージョン、環境、入力、ユーザー、またはデータの状態；
• 証拠がある場合は、最後に正常だった状態；
• 影響、緊急度、および安全に再現できる範囲。

実装に合わせて、期待される動作を暗黙に再定義してはいけません。仕様が曖昧な場合は、その曖昧さを明らかにし、どちらかの動作を不具合と見なす前に、リポジトリ内の証拠またはユーザーの指示を確認します。

証拠をたどって原因を特定する

原因が不明な場合、複数の仮説が考えられる場合、または履歴や制御された実験を通じてリグレッションの範囲を絞り込む必要がある場合は、references/evidence-driven-diagnosis.mdを確認します。

症状の原因となり得る境界をまたいで、障害の経路をたどります。周辺のコードから推測するのではなく、実際の値、状態遷移、設定、永続化、外部からの応答、タイミングを調べます。反証可能な仮説を少数に絞り、まず最も低コストで仮説を判別できる確認を行います。

以下を区別します。

• **トリガー：**障害を顕在化させる入力または条件；
• **根本原因：**障害を可能にする、不変条件への違反または誤った動作；
• **増幅要因：**影響を拡大するリトライ、キャッシュ、並行処理、古い状態、またはエラー処理；
• **症状：**ユーザーに見える結果、または運用上の結果。

最初に見つかった不審な行、例外が発生した箇所、または相関するイベントだけで調査を終えてはいけません。スタックフレームが示すのは障害が表面化した場所であり、発生源とは限りません。

ランタイムの境界を安全に診断する

環境に依存する障害、非同期または並行動作、キュー、キャッシュ、データベース、外部サービス、リソース枯渇、または本番環境のテレメトリーについては、references/runtime-and-distributed-failures.mdを確認します。

• 計測を追加する前に、既存のログ、トレース、メトリクス、エラーレポート、安全なローカル再現を優先します。
• 診断情報から、秘密情報、トークン、個人データ、機密性の高いペイロードを削除します。
• 明示的な許可とロールバック計画なしに、本番トラフィックで実験したり、共有データを変更したり、安全策を無効にしたり、広範囲のログ出力を増やしたりしてはいけません。
• 仕様上正しい動作だと確認できない限り、タイムアウトの延長、リトライ、キャッシュのクリア、プロセスの再起動、例外の握りつぶしを根本原因への修正と見なしてはいけません。

原因を特定した境界で修正する

証拠によって原因を特定したら、次の手順を実施します。

1. 原因に至る一連の流れを、簡潔な説明としてまとめます；
2. 違反された仕様を管轄する境界を変更します；
3. 互換性と無関係な動作を維持します；
4. 一時的な診断処理のうち、ノイズが多いもの、機密性に問題があるもの、または不要になったものを削除します；
5. 実用的かつ信頼できる場合は、リグレッションテストを追加または更新します；
6. 元の再現手順と、関連する周辺動作を検証します。

証拠によって疑われたコード上の不具合が否定された場合は、無理にコードを変更せず、実際の原因を報告します。原因がまだ不明な場合は、結果が部分的なものであることを明示し、次に行うべき判別力のある観察または実験を示します。

確信度を正直に報告する

以下を報告します。

• 症状と確認できた影響範囲；
• 調査した証拠と再現状況；
• 根本原因。関連する場合は、トリガーと増幅要因を分けて説明します；
• 修正内容と、その修正が原因の仕組みに対処できる理由；
• 実施した検証とその結果；
• 残る不確実性、未検証の環境、運用上の追加対応。

ローカルテストに合格しただけで、本番環境限定のインシデントが解決したと主張してはいけません。結果が再現済み、影響緩和済み、修正済み、または調査継続中のいずれであるかを明示します。

スキルを必要な範囲で組み合わせる

• 主なタスクが、確認された障害の診断ではなく変更セットの評価である場合は、superior-code-review を使用します。
• 確認済みの修正によって、ドメインルール、永続化、状態遷移、または API の動作が変わる場合は、superior-logic を使用します。
• 確認済みの原因に、スキーマ、クエリ、トランザクション、マイグレーション、またはデータ修復への対応が必要な場合は、superior-database を使用します。
• 確認済みの原因から、測定に基づく最適化、キャパシティ分析、またはパフォーマンス予算の設定が必要になった場合は、superior-performance を使用します。
• 確認済みの原因に、レジリエンス、縮退運転、復旧、アラート、またはランブックの変更が必要な場合は、superior-reliability を使用します。
• 障害がパイプライン、成果物、ロールアウト、または環境への昇格に関わる場合は、superior-delivery を使用します。
• 回帰テストの設計、テストの分離、または不安定なテストの診断が主な課題になった場合は、superior-testing を使用します。
• 障害によって、認可、検証、悪用、トークン、SSRF、または情報漏えいに関する脆弱性が明らかになった場合は、superior-api-security を使用します。
• 重要な修正を検証した後、または長期的に有用な診断・復旧手順を変更する場合は、superior-docs を使用します。

診断を、無関係なリファクタリング、オブザーバビリティプラットフォームの導入、パフォーマンス最適化、またはアーキテクチャの再設計にまで広げないでください。