systematic-debugging

系統的なデバッグ

厳密なデバッグワークフローです。バグ、テストの失敗、予期しない動作に対処する際に使用します。

3 つの主な目的：

1. 症状ではなく、原因を修正する。
2. 推測に基づく修正を防ぐ。
3. 修正前に、失敗をテストで確実に捉える。

厳守事項

以下のルールに例外はありません。

1. 再現可能または観測可能な状態になるまで修正しない。
2. 根本原因の仮説を立てるまで修正しない。
3. 失敗するテスト、または同等の再現手段を用意するまで修正しない。
4. 一度に検証する仮説は 1 つだけにする。
5. 修正のついでにリファクタリングしない。
6. 修正を 3 回試しても失敗する場合は、さらにパッチを適用する前に構造上の問題を疑う。

このプロセスに違反した場合、デバッグの失敗とみなされます。

使用する場面

以下の状況でこのスキルを使用します。

• テストが失敗したとき
• 本番環境またはローカル環境でバグが発生したとき
• レスポンス、状態、レンダリング、クエリ結果が期待と異なるとき
• パフォーマンスの低下、タイムアウト、競合状態、断続的な失敗を調査するとき
• 一度以上修正した問題が再発したとき

以下のような言い訳は認められません。

• 「簡単そうだから、直接修正してしまおう」
• 「時間がないので、パッチを当てて先に進もう」
• 「たぶんこれが原因だから、とりあえず変更してみよう」

必須の出力項目

このスキルを使用するときは、以下の項目を内部で必ず確定してください。

1. 問題の説明：何が起きたのかを 1 文で定義する
2. 再現手順：失敗を再現または観測する方法
3. 証拠：実際に観測した結果
4. 根本原因の仮説：この問題が起きると考える理由
5. 失敗を検出する仕組み：失敗するテスト、再現スクリプト、ログ検証のいずれか
6. 修正：根本原因を対象とする単一の修正
7. 検証：修正後の再現手順と関連するテスト結果

この 7 項目のうち 1 つでも欠けていれば、作業は完了していません。

ワークフロー

以下の手順を順番に実行してください。

フェーズ 1. 問題を定義する

まず、問題を簡潔にまとめます。

• 期待される動作は何か
• 観測された動作は何か
• 影響範囲はどこまでか
• 常に再現するか、断続的に発生するか

出力形式：

Problem: <expected> but got <actual> under <condition>

症状と推測を混同しないでください。

Good: Product detail API returns 500 when brand is null.
Bad: Serializer is broken because brand mapping seems wrong.

フェーズ 2. 再現または計測する

修正する前に、失敗を再び確認できる必要があります。

優先順位：

1. 既存のテストで再現する
2. 最小限の統合テストで再現する
3. 単体テストで再現する
4. 再現スクリプトまたはコマンドで観測する
5. ログまたは計測を追加して観測する

ルール：

• 再現手順はできるだけ簡潔にしてください。
• バグが UI でしか確認できない場合でも、可能であれば下位レイヤーでの再現を優先してください。
• 断続的な失敗の場合は、ログの追加、入力値の記録、タイムスタンプや並行実行の条件の取得によって観測可能性を高めてください。
• 再現できない場合は、修正に進まず、観測可能性を高めてください。

再現できない場合に行うこと：

1. 入力値を記録する
2. 環境の違いを確認する
3. 最近の変更を確認する
4. 境界となる箇所にログを追加する
5. 同じ症状を引き起こす、より限定的な条件を探す

フェーズ 3. 証拠を集める

観測可能な事実のみを収集します。

必ず確認する項目：

• エラーメッセージとスタックトレースの全文
• 失敗した入力値
• 最近変更されたファイルまたはコミット
• 環境や設定の違い
• 呼び出し経路とデータフロー

複数のコンポーネントにまたがる問題では、各境界で確認してください。

例：

• コントローラー -> アプリケーション -> サービス -> リポジトリ
• クライアント -> API -> 外部サービス
• スケジューラー -> バッチサービス -> データベース

各境界で、以下を確認してください。

• 何が入力されたか
• 何が出力されたか
• どの値が変換されたか
• どのような条件で問題が発生するか

問題の箇所を特定するまで、修正しないでください。

フェーズ 4. 根本原因を特定する

原因候補を必ず 1 つだけ立てます。

形式：

Hypothesis: <root cause> because <evidence>

優れた仮説の条件：

• 原因を 1 つに絞っている
• 観測された証拠と結び付いている
• 小規模な実験で否定できる

悪い仮説の例：

• 「どこかに非同期処理の問題がありそうです」
• 「シリアライズ層全体が不安定なようです」

原因をたどって発生源までさかのぼります。スタックの深いところでエラーが現れた場合は、症状ではなく入力の発生源をたどります。

フェーズ 5. 失敗を固定する

修正する前に、失敗を固定します。

優先順位：

1. 自動化された失敗テスト
2. 既存のテストに回帰ケースを追加
3. 最小限の再現スクリプト
4. ログやアサーションによる一時的な検証

ルール：

• 可能な限り自動テストを作成します。
• 修正前に失敗する必要があります。
• 修正後は、同じ経路で成功する必要があります。
• テスト名から何が壊れたのかが分かるようにします。

自動テストが実行可能な場合は、このスキルと併せて test-driven-development スキルを使用します。

フェーズ 6. 単一の修正を実装する

修正は、1 つの仮説だけに対処します。

許可されること：

• 原因に直接対処する最小限のコード変更
• 検証に必要な最小限の補助的変更

禁止事項：

• 一見関連する複数の修正をまとめること
• 修正とリファクタリングを組み合わせること
• 書式設定、クリーンアップ、名前変更をこっそり追加すること
• 証拠なしに null ガードを追加すること
• 例外を握りつぶすこと

修正に失敗した場合は、直ちにフェーズ 1 またはフェーズ 3 に戻ります。以前の仮説が誤っていたということです。

フェーズ 7. 検証して完了する

完了前に、以下のすべてを満たす必要があります。

1. 元の再現経路で失敗しなくなっている。
2. 新しい失敗ガードが成功している。
3. 関連するテストに問題がない。
4. 修正が症状ではなく原因を防いでいることを説明できる。

断続的に発生するバグの場合、1 回成功しただけでは不十分です。繰り返し実行したり、条件を変えたりして検証する必要があります。

停止条件

以下の場合は停止し、問題を捉え直します。

1. 再現に失敗した

何度か試しても再現できない場合：

• 可観測性が不十分かどうかを確認します。
• 環境に違いがないか確認します。
• 問題の定義が誤っていないか確認します。

再現せずにコードを変更することは禁止です。

2. 修正が 3 回失敗した

3 回連続で修正が的を外した場合は、次のいずれかと結論付けます。

• 現在の理解が誤っている
• 問題は構造的なものである可能性が高い（共有状態、境界設計、責任の分離）

この時点で「4 回目のパッチ」を当てるのは解決策ではありません。構造についての議論が必要です。

3. 失敗ガードがない

失敗するテスト、またはそれに相当する再現手段を作成できない場合は、完了と宣言しないでください。少なくとも、再現コマンドと観測結果を残します。

危険な兆候

次のような考えが浮かんだら、直ちに停止して前のフェーズに戻ります。

• 「この 1 行を変えれば、うまくいくはずです」
• 「ログはあとで確認します。先に修正しましょう」
• 「テストはあとで追加します」
• 「これとあれを一度に修正しましょう」
• 「エラーが消えたので、原因を知る必要はありません」

最小チェックリスト

実行中の自己検証にこのチェックリストを使用します。

• 問題を 1 文で定義した
• 失敗を再現した、または観測可能にした
• 証拠を集めた
• 根本原因の仮説を 1 つ立てた
• 修正前に失敗するガードを作成した
• 単一の修正だけを適用した
• 修正後、同じ経路で検証した

完了基準

このスキルの完了基準は「コードが変更された」ことではありません。

完了基準：

• 問題が明確に定義されている
• 修正前に失敗が固定されている
• 修正が根本原因に結び付いている
• 検証結果が残っている

この 4 つを満たさなければ、デバッグは完了していません。