体系的デバッグ

概要

根拠のない修正は時間を無駄にし、新しいバグを生み出します。応急処置は根本的な問題を隠すだけです。

コア原則： 修正を試みる前に、必ず根本原因を特定します。症状に対する修正は失敗です。

このプロセスの文字通りの違反は、デバッグの本質を違反することです。

鉄則

根本原因の調査なしに修正を行わない

Phase 1 を完了していない場合、修正を提案することはできません。

いつ使うか

あらゆる技術的問題に使用します：

• テストの失敗
• 本番環境でのバグ
• 予期しない動作
• パフォーマンスの問題
• ビルドの失敗
• 統合の問題

特にこの場合に使用します：

• 時間的プレッシャーがある場合（緊急時は推測に頼りやすい）
• 「ちょっとした修正」が明白に見える場合
• 既に複数の修正を試みた場合
• 前の修正がうまくいかなかった場合
• 問題を完全に理解していない場合

スキップしてはいけない場合：

• 問題が簡単に見える場合（簡単なバグにも根本原因があります）
• 急いでいる場合（急ぐと必ずやり直しが発生します）
• マネージャーが「今すぐ修正しろ」と言っている場合（体系的なアプローチは試行錯誤より高速です）

4 つのフェーズ

各フェーズを完了してから次に進む必要があります。

Phase 1: 根本原因の調査

修正を試みる前に：

1. エラーメッセージを注意深く読む

   • エラーや警告を飛ばさない
   • 正確な解決策を含んでいることが多い
   • スタックトレース全体を読む
   • 行番号、ファイルパス、エラーコードをメモする

2. 一貫して再現できるか確認する

   • 確実にトリガーできるか？
   • 正確な手順は？
   • 毎回発生するか？
   • 再現不可能な場合 → より多くのデータを収集し、推測しない

3. 最近の変更をチェックする

   • これを引き起こす可能性のある変更は？
   • Git diff、最近のコミット
   • 新しい依存関係、設定の変更
   • 環境の違い

4. マルチコンポーネントシステムでエビデンスを収集する

   システムに複数のコンポーネントがある場合（CI → ビルド → 署名、API → サービス → データベース）：

   修正を提案する前に、診断機器を追加します：

   各コンポーネント境界ごと：
     - コンポーネントに入るデータをログに記録
     - コンポーネントを出るデータをログに記録
     - 環境/設定の伝播を検証
     - 各レイヤーの状態をチェック
   
   1回実行して、どこで失敗するかを示すエビデンスを収集
   その後、エビデンスを分析して失敗しているコンポーネントを特定
   その後、その特定のコンポーネントを調査
   

   例（マルチレイヤーシステム）：

   # Layer 1: ワークフロー
   echo "=== ワークフローで利用可能なシークレット: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: ビルドスクリプト
   echo "=== ビルドスクリプトの環境変数: ==="
   env | grep IDENTITY || echo "IDENTITY が環境にない"
   
   # Layer 3: 署名スクリプト
   echo "=== キーチェーンの状態: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: 実際の署名
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   これが明らかにするもの： どのレイヤーが失敗するか（シークレット → ワークフロー ✓、ワークフロー → ビルド ✗）

5. データフローをトレースする

   エラーがコールスタックの深くにある場合：

   このディレクトリの root-cause-tracing.md を参照して、完全な逆向きトレース技術を確認してください。

   クイックバージョン：

   • 不正な値はどこで発生するのか？
   • これを不正な値で呼び出したのは？
   • ソースが見つかるまでトレースを続ける
   • 症状ではなくソースで修正する

Phase 2: パターン分析

修正する前にパターンを見つける：

1. 動作している例を見つける

   • 同じコードベース内の同様の動作しているコードを見つける
   • 壊れているものと似ていて動作しているものは？

2. リファレンスに対して比較する

   • パターンを実装する場合、リファレンス実装を完全に読む
   • ざっと読まない - すべての行を読む
   • 適用する前にパターンを完全に理解する

3. 違いを特定する

   • 動作しているものと壊れているものの違いは？
   • すべての違いをリストアップする（どんなに小さくても）
   • 「それは関係ないはず」と仮定しない

4. 依存関係を理解する

   • これが必要とする他のコンポーネントは？
   • どんな設定、設定ファイル、環境が必要？
   • どんな前提があるか？

Phase 3: 仮説とテスト

科学的方法：

1. 単一の仮説を立てる

   • 明確に述べる：「Y という理由で X が根本原因だと思う」
   • それを書き留める
   • あいまいでなく、具体的に

2. 最小限でテストする

   • 仮説をテストするために最小限の変更を行う
   • 一度に 1 つの変数だけ
   • 複数のことを一度に修正しない

3. 続行する前に検証する

   • うまくいったか？ はい → Phase 4
   • うまくいかなかった？ 新しい仮説を立てる
   • 上に更に修正を重ねない

4. わからないとき

   • 「X を理解していない」と言う
   • わかっているふりをしない
   • 助けを求める
   • もっと調べる

Phase 4: 実装

症状ではなく根本原因を修正する：

1. 失敗するテストケースを作成する

   • 最も単純な再現可能な形
   • 可能であれば自動テスト
   • フレームワークがない場合は 1 回限りのテストスクリプト
   • 修正する前に必須
   • 適切な失敗するテストを書くために superpowers:test-driven-development スキルを使用します

2. 単一の修正を実装する

   • 特定された根本原因に対処する
   • 一度に 1 つの変更のみ
   • 「ついでに」改善はしない
   • バンドルされたリファクタリングはしない

3. 修正を検証する

   • テストが通るようになった？
   • 他のテストが壊れていない？
   • 問題は実際に解決されたか？

4. 修正がうまくいかない場合

   • 停止
   • カウント：何回の修正を試みましたか？
   • 3 回未満の場合：Phase 1 に戻り、新しい情報で再分析
   • 3 回以上の場合：停止してアーキテクチャに疑問を投げかける（以下のステップ 5 を参照）
   • 建築的な議論なしに修正 #4 を試みない

5. 3 つ以上の修正が失敗した場合：アーキテクチャに疑問を投げかける

   アーキテクチャの問題を示すパターン：

   • 各修正は異なる場所での新しい共有状態/カップリング/問題を明らかにする
   • 修正には「大規模なリファクタリング」が必要
   • 各修正は他の場所で新しい症状を生成する

   根本的に疑問を投げかけるために停止：

   • このパターンは根本的に健全か？
   • 「純粋な慣性で続けている」のか？
   • 症状を修正し続けるのではなくアーキテクチャをリファクタリングすべきか？

   さらに修正を試みる前にあなたの人間パートナーと議論する

   これは失敗した仮説ではありません - これは間違ったアーキテクチャです。

レッドフラグ - 停止してプロセスに従う

自分自身がこう考えていることに気づいたら：

• 「今のところ応急処置で、後で調査する」
• 「X を変更してみて、どうなるか見てみよう」
• 「複数の変更を加えてテストを実行する」
• 「テストをスキップして、手動で検証する」
• 「多分 X だろう、それを修正してみよう」
• 「完全には理解していないが、これは機能するかもしれない」
• 「パターンは X と言っているが、異なる方法で適応させる」
• 「主な問題は以下の通りです：[調査なしに修正をリストアップ]」
• データフローをトレースする前にソリューションを提案する
• 「もう 1 回の修正試行」（既に 2 回以上試みた場合）
• 各修正が異なる場所の新しい問題を明らかにする

これらはすべて意味します：停止。Phase 1 に戻る。

3 つ以上の修正が失敗した場合： アーキテクチャに疑問を投げかける（Phase 4.5 を参照）

あなたの人間パートナーが表示するあなたが間違っていることのシグナル

これらのリダイレクションに注目：

• 「それは起こっていないのか？」 - あなたは検証せずに仮定した
• 「それは私たちに...を示しますか？」 - エビデンス収集を追加すべきだった
• 「推測するのをやめろ」 - あなたは理解せずに修正を提案している
• 「これを超思考する」 - 症状だけでなく基本に疑問を投げかける
• 「私たちは立ち往生しているか？」（イライラしている） - あなたのアプローチは機能していない

これらを見たとき： 停止。Phase 1 に戻る。

一般的な言い訳

言い訳	実際
「問題は簡単で、プロセスは不要」	簡単な問題にも根本原因があります。プロセスは簡単なバグに対して高速です。
「緊急なので、プロセスの時間がない」	体系的デバッグは試行錯誤の方針転換より高速です。
「まずこれを試して、その後調査する」	最初の修正がパターンを設定します。最初から正しくやる。
「修正が機能することを確認してからテストを書く」	テストされていない修正は定着しません。テストが最初にそれを証明します。
「複数の修正を一度に行えば時間節約」	何が機能したかを特定できない。新しいバグを引き起こす。
「リファレンスが長すぎる、パターンを適応させる」	部分的な理解はバグを保証します。完全に読む。
「問題が見える、修正しよう」	症状が見える ≠ 根本原因を理解する。
「もう 1 回の修正試行」（2 回以上失敗後）	3 回以上の失敗 = アーキテクチャの問題。もう一度修正するのではなくパターンに疑問を投げかける。

クイックリファレンス

フェーズ	主な活動	成功基準
1. 根本原因	エラーを読む、再現、変更をチェック、エビデンスを収集	何と何を理解する
2. パターン	動作している例を見つける、比較	違いを特定
3. 仮説	理論を立てる、最小限でテスト	確認または新しい仮説
4. 実装	テストを作成、修正、検証	バグが解決、テストが成功

プロセスが「根本原因なし」を明らかにするとき

体系的な調査が問題が真に環境的、タイミング依存、または外部的であることを明らかにする場合：

1. プロセスを完了してください
2. 調査したことを文書化する
3. 適切な処理を実装する（再試行、タイムアウト、エラーメッセージ）
4. 将来の調査のための監視/ロギングを追加

しかし： 「根本原因なし」のケースの 95% は調査不完全です。

サポート技術

これらの技術はシステム的なデバッグの一部であり、このディレクトリで利用可能です：

• root-cause-tracing.md - コールスタックを通じてバグを逆にトレースして元のトリガーを見つける
• defense-in-depth.md - 根本原因を見つけた後、複数のレイヤーで検証を追加
• condition-based-waiting.md - 任意のタイムアウトを条件ポーリングで置き換える

関連スキル：

• superpowers:test-driven-development - 失敗するテストケースを作成するため（Phase 4、ステップ 1）
• superpowers:verification-before-completion - 修正が機能したことを成功を主張する前に検証

実世界への影響

デバッグセッションから：

• 体系的なアプローチ：15～30 分で修正
• ランダムな修正アプローチ：2～3 時間の方針転換
• 初回修正率：95% vs 40%
• 導入された新しいバグ：ほぼゼロ vs 一般的

制限事項

• このスキルを上記で説明されたスコープと明確に一致するタスクにのみ使用します。
• 出力を環境固有の検証、テスト、または専門家レビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、停止して説明を求めてください。