specsfy-specialist-debugging

診断

使用する場合

• 信頼できる再現方法がまだ確立されているかどうかにかかわらず、観測された動作が期待される動作と異なる場合に使用します。
• 間欠的な障害（「フレーキー」）、デプロイ後のリグレッション、または具体的な症状（タイムアウト、エラー、報告された遅延）を伴うパフォーマンス低下にも使用します。
• すでに正常に動作していて症状もないシステムの最適化には使用しません。それは $specsfy-specialist-performance-engineering の担当であり、障害ではなく SLO を起点とします。
• 本番環境で適切な boundary を計測するのに十分なシグナルが得られない場合は、$specsfy-specialist-observability と組み合わせます。

フロー

1. 期待される動作、観測された動作、正確な環境、直近の発生時刻と頻度を記録します。これらがなければ、仮説は当てずっぽうです。
2. 信頼できる再現方法を構築します。直接再現できない場合は、障害と相関する、観測可能かつ繰り返し確認できるシグナル（ログ、メトリクス、トレース）を用意します。
3. 障害が再現する最小のケースになるまで、入力、関連コンポーネント、時間範囲を絞り込みます。取り除いても結果が変わらない要素は、それぞれ仮説から除外できる変数です。
4. 検証可能な仮説を立て、観測された症状に基づいて、興味深さではなく、テストのしやすさと可能性の高さで順序付けします。
5. 残る仮説を最も明確に判別できる boundary、つまり、一方の仮説がある値を予測し、もう一方が別の値を予測する点を計測します。
6. 原因、影響範囲（その経路だけか、呼び出しのクラス全体か）、および原因が症状を生み出す正確な仕組みを特定します。
7. 修正を許可されている場合は、原因を取り除く最小限の変更を適用し、その修正がなければ失敗するリグレッションテストを追加します。

パターン

• 一度に変更する原因候補は一つだけにします。二つのものを同時に変更すると、症状が消えたときに原因を特定できなくなります。
• 時間的な相関と因果関係を区別します。「デプロイ X の後に始まった」は手がかりであり、仕組みを切り分けるまでは証明ではありません。
• プロセスを再起動したり状態を消去したりする前に、証拠（ログ、状態、ダンプ）を保全します。障害が発生した環境は、その後再現できなくなる可能性があります。
• 正常な環境と異常な環境を体系的に比較します。バージョン、設定、データ、負荷、操作順序を同一にし、一度に一つの要因だけを変えます。
• フレーキーな挙動は、反証が得られるまでは、並行処理、タイミング、共有状態、外部依存関係の症状として扱います。「もう一度実行すればよい」と片付けてはいけません。
• 診断を終える前に、一時的、冗長、または機微な情報（個人情報、シークレット）を含む計測を取り除きます。
• 原因は、症状のレベル（「ときどき失敗する」）だけでなく、仕組みのレベル（「X と Y の間の競合状態により、書き込みの完了前に読み取りが可能になる」）で説明します。

アンチパターン

• 事前に仮説を立てずに「print を追加してもう一度実行する」こと。ノイズが増えるだけで、調査範囲が狭まることはほとんどなく、場当たり的な試行と区別できないこともよくあります。
• エラーが最初に現れた箇所を、そこが原因なのか、単に影響が見える場所なのかを確認せずに修正すること（NullPointerException は、発生箇所で原因が生じるとは限りません）。
• 手動での再現が一度失敗しなくなっただけで「修正済み」と判断すること。自動化された決定論的な再現がなければ、症状がなくなったのは単なる偶然やタイミングの変化かもしれません。
• フレーキーなテストを調査せずに「不安定で、無関係」として無視すること。ほとんどの場合、フレーキーさは抑え込むべきノイズではなく、実際の並行処理または共有状態のバグを示す証拠です。

検証

• 修正前は再現手順が確実に失敗し、同じ環境で修正後は確実に成功します。
• 追加した回帰テストは、修正を戻したときに正しい理由で失敗します（偶発的な別の理由ではありません）。
• 修正した経路に隣接するシナリオについて、変更による副作用がないか確認しています。
• 原因（仕組み）、それを裏付ける証拠、追加した予防策（テスト、不変条件、アラーム）を簡潔に記録しています。
• こうした証拠がない限り、原因が「解決済み」と宣言しないでください。再現や回帰テストなしに直感で原因を特定することは禁止です。

関連スキル

• $specsfy-specialist-server-report は、Ansible による読み取り専用の収集を通じて、ホストごとにログ、サービス、ディスク使用量をまとめたレポートを作成します。

• $specsfy-specialist-technical-research は、原因の特定に一次資料が必要な場合に、外部の動作、正誤表、互換性を確認します。

• $specsfy-specialist-observability は、利用可能なシグナルでは仮説を区別するのに不十分な場合に、本番環境の計測を行います。

• $specsfy-specialist-performance-engineering は、機能上のエラーを伴わない性能低下の場合に使用します。ここでの根本原因の診断により、どの最適化にコストをかける価値があるかをこのスキルに判断してもらえることがあります。

• $specsfy-specialist-code-review は、マージ前に修正と回帰テストをレビューします。

再現と切り分けの手法、flakiness の一般的な原因、環境ごとのツール、公式情報源については、references/standards.md を参照してください。