performing-systematic-debugging-for-stubborn-problems

Fagan インスペクションによる体系的なデバッグ

このスキルでは、複雑な問題や、何度も修正を試みても解決しない頑固なバグに直面したとき、修正版の Fagan インスペクション手法を適用して体系的に問題を解決します。

プロセスの概要

次の4つのフェーズを順番に進めてください。フェーズを飛ばしたり、インスペクションが完了する前に修正を試みたりしないでください。

フェーズ 1：初期概要

分析の前に、問題を明確に把握します。

• 問題を説明する — 専門用語を使わず、平易な言葉で説明します
• 期待される動作を示す — 本来どのように動作するべきかを示します
• 実際の動作を示す — 代わりに何が起きているかを示します
• 症状を記録する — エラーメッセージ、ログ、観測可能な障害を記録します
• 状況 — いつ、どのくらいの頻度で、どのような条件下で発生するかを示します

出力： 誰もが理解できる明確な問題の説明。

フェーズ 2：体系的なインスペクション

Fagan インスペクションの「読み手」役として、コードを1行ずつ確認します。まだ修正は試みず、欠陥を特定してください。この段階では純粋にインスペクションを行います。

次の欠陥カテゴリを基に確認します。

1. ロジックエラー

   • 条件ロジックの誤り（演算子の間違い、条件の反転）
   • ループ条件の問題（無限ループ、早期終了）
   • 制御フローの問題（到達不能なコード、誤った実行経路）

2. 境界条件

   • オフバイワンエラー
   • エッジケース（空の入力、null 値、最大値）
   • 配列／コレクションの範囲

3. エラー処理

   • 未処理の例外
   • バリデーションの不足
   • サイレントエラー（エラーを捕捉しているが、ログに記録されない）
   • 不適切なエラー復旧

4. データフローの問題

   • 変数スコープの問題
   • データ変換エラー
   • 型の不一致や型変換の問題
   • 状態管理（古いデータ、競合状態）

5. 統合ポイント

   • API 呼び出し（エンドポイントの誤り、不正なリクエスト、不足しているヘッダー）
   • データベースとのやり取り（クエリエラー、トランザクション処理）
   • 外部依存関係（バージョンの不一致、設定の問題）
   • タイミングの問題（async/await の問題、競合状態）

このフェーズでは考えを声に出して説明します。コードの各セクションについて、次のことを行います。

• コードが何を意図しているかを述べる
• 意図と実装の食い違いを特定する
• 前提や不明瞭な点を指摘する
• 複雑なセクションについては ultrathink を使って、さらに深く考察する

出力： 特定した欠陥をカテゴリ別にまとめたリスト。行番号と具体的な説明を含めます。

フェーズ 3：根本原因の分析

問題を特定したら、症状だけでなく根本原因を突き止めるため、原因をさかのぼって調べます。

5つのなぜの手法：

• 根本の問題にたどり着くまで、「なぜ」を繰り返し問いかけます（少なくとも3〜5回）。
• 分析では、それぞれの「なぜ」を明示します。
• 例：
  • API 呼び出しはなぜ失敗したのか？ → リクエストの形式が正しくなかったため
  • なぜ形式が正しくなかったのか？ → データが正しくシリアライズされなかったため
  • なぜシリアライズされなかったのか？ → シリアライザーが別の型を想定していたため
  • なぜ別の型を想定していたのか？ → スキーマは更新されたが、コードは更新されなかったため
  • 根本原因：サービス間でスキーマのバージョンが一致していない

考慮事項：

• 環境要因（設定、依存関係、実行環境）
• タイミングと並行処理（競合状態、非同期処理の問題）
• コードやシステム設計に隠れた前提
• 履歴情報（最近の変更、移行、更新）

前提を明示する：

• 「……という理由から、X と仮定しています」
• 「これは、Y が常に……であることを前提としています」
• 検証が必要な前提があれば指摘します

出力： 根本原因、その結論に至った推論の経緯、および検証が必要な前提を明確に示します。

フェーズ 4：解決策と検証

特定した各問題に対して、具体的な修正案を提示します。

各修正案について：

1. 修正内容を説明する - 必要なコードや設定の変更
2. 根本原因が解決する理由を説明する - フェーズ 3 の分析との関連を示す
3. 副作用を考慮する - この変更がほかにどのような影響を及ぼす可能性があるか
4. 検証手順を定める - 修正が機能することを確認する方法

検証計画：

• このバグを検出できた具体的なテストケース
• 手動での検証手順
• 追加するモニタリングやログ
• 検証するエッジケース

出力： 検証手順を含む、構造化された修正案のリスト。

重要なガイドライン

• 次のフェーズに進む前に、各フェーズを十分に完了する
• 考えながら話す - 推論の過程を通して言語化する
• 前提を暗黙に置かず、明示する
• 不明確な点は推測せず、指摘する - 確かでない場合は、その旨を伝える
• 利用可能なツールを使う - ファイルを読み、コードを検索し、テストを実行し、ログを確認する
• 手早い修正より体系的な分析を重視する
• 指摘した点を検証する - すべてのフェーズを完了した後、不明確な点を再確認し、必要に応じて think ツールを「ultra」の深度で使って明らかにする

最終出力

4 つすべてのフェーズを完了した後、以下を提示します。

1. 調査結果の概要 - 主な不具合と根本原因
2. 修正案 - 理由を添えた優先順位付きリスト
3. 検証計画 - 修正が機能することを確認する方法
4. 次のステップ - ユーザーから別途指示がない限り、提案した修正の実装に進む

このスキルを使用すべきでない場合

• 単純で明白なバグで、修正方法も明確な場合
• 最初のデバッグ作業がまだ進行中の場合
• 新機能の場合（このスキルは既存コードのデバッグを対象とします）
• 問題が明らかに環境（設定、インフラストラクチャ）に起因し、コードの調査を必要としない場合