systematic-debugging

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

このスキルでは、複雑な問題や、複数回の修正を試みても解決しない頑固なバグに直面した際に、体系的に問題を解決するための、変更を加えた Fagan インスペクション手法を適用します。

プロセスの概要

4 つのフェーズそれぞれにタスクを作成し、次のフェーズに進む前に現在のフェーズを完了して、完了済みとしてマークします。

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

フェーズ 1：初期概要

分析の前に、問題を明確に理解します。

• 問題を説明する：専門用語を使わず、平易な言葉で説明します
• 期待される動作を述べる：本来どう動作するべきかを示します
• 実際の動作を述べる：代わりに何が起きているかを示します
• 症状を記録する：エラーメッセージ、ログ、観察できる障害などを記載します
• 状況：いつ、どのくらいの頻度で、どのような条件下で発生するかを示します
• これまでに試した修正：試した修正をそれぞれ挙げ、変更内容と失敗した理由を記載します。これらは除外済みの仮説として扱い、フェーズ 3 で考慮する必要があります

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

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

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

次の欠陥カテゴリに照らして確認します。

1. ロジックエラー
2. 境界条件
3. エラー処理
4. データフローの問題
5. 統合ポイント

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

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

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

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

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

5 Whys 手法：

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

検討事項：

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

前提を明示する：

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

出力： 根本原因、そこに至った推論の過程、検証が必要な前提を明確に記述したもの。

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

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

解決策ごとに、次のことを行います。

1. 修正内容を説明する：必要なコードや設定の変更を記載します
2. 根本原因が解消される理由を説明する：フェーズ 3 の分析と関連付けます
3. 副作用を検討する：ほかにどのような影響があり得るかを考えます
4. 検証手順を定める：修正が機能することをどう確認するかを示します

検証計画：

• このバグを検出できたはずの具体的なテストケース
• 手動での検証手順
• 追加する監視やログ
• 検証するエッジケース

サブエージェントを壁打ち相手として使い、提案する解決策と検証計画に対する批判的なフィードバックを得ます。

出力： 調査結果（主な欠陥と根本原因）の概要、根拠を添えた優先順位付きの修正案リスト、修正が機能することを確認するための検証計画。

重要なガイドライン

• 次の段階に進む前に、各フェーズを十分に完了してください
• 不明確な点は推測せず、明示してください — 不確かな場合は、その旨を伝えてください
• 利用可能なツールを使ってください — ファイルの読み取り、コードの検索、テストの実行、ログの確認を行ってください
• 手早い修正より、体系的な分析を重視してください
• 明示した不明点を検証してください — すべてのフェーズを完了した後、不明な点を再確認し、必要に応じて think ツールを「ultra」の深度で使って明らかにしてください

最終出力

4 つすべてのフェーズを完了した後、ユーザーから別途指示がない限り、提案した解決策の実装に進んでください。

このスキルを使用しない場合

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