体系的なデバッグ

概要

無計画な修正は時間を浪費し、新たなバグを生み出します。その場しのぎのパッチは根本的な問題を隠蔽するだけです。

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

タイプ： 厳密(RIGID) - 正確に従うこと。この規律から適応してはいけません。

このプロセスの文字を違反することは、デバッグの精神を違反することです。

鉄則

根本原因調査なしに修正なし

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

使用する場合

以下のような技術的問題に使用します：

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

特に以下の場合に使用します：

時間的な圧力がある場合（緊急事態は推測を誘発します）
「ちょっと簡単な修正」に見える場合
複数の修正を既に試している場合
前回の修正が機能しなかった場合
問題を完全に理解していない場合

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

問題が単純に見える場合（単純なバグにも根本原因があります）
急いでいる場合（体系的なアプローチは推測よりも速いです）
マネージャーが今すぐ修正してほしいと言う場合（体系的なアプローチは推測よりも速いです）

4 つの Phase

次に進む前に各 Phase を完了します。

Phase 1：根本原因調査

修正を試みる前に：

エラーメッセージを慎重に読む
- エラーや警告をスキップしない
- 正確な解決策が含まれていることが多い
- スタックトレースを完全に読む
- 行番号、ファイルパス、エラーコードを記録する
一貫して再現する
- 確実にトリガーできるか？
- 正確な手順は何か？
- 毎回発生するか？
- 再現可能でない場合、推測せずにデータを収集する
最近の変更を確認する
- これの原因となる変更は何か？
- Git diff、最近のコミット
- 新しい依存関係、設定の変更
- 環境の違い

複数コンポーネントシステムの証拠収集

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

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

コンポーネント境界ごと：
  - コンポーネントに入るデータをログ出力
  - コンポーネントから出るデータをログ出力
  - 環境/設定の伝播を確認
  - 各レイヤーの状態を確認

一度実行して破損が「どこで」発生するかを示す証拠を収集
そして証拠を分析して失敗しているコンポーネントを特定
そしてそのコンポーネントを調査

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

エラーがコールスタックの深いところにある場合：
- 不良な値はどこから発生するか？
- 不良な値でこれを呼び出したのは何か？
- ソースを見つけるまでトレースし続ける
- 症状ではなくソースで修正する

Phase 2：パターン分析

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

動作している例を探す
- 同じコードベース内の類似した動作しているコードを見つける
- 壊れているものに似た何が機能しているか？
リファレンスに対して比較する
- パターンを実装する場合、リファレンス実装を完全に読む
- スキップしない - すべての行を読む
- 適用する前にパターン全体を理解する
差異を特定する
- 動作しているものと壊れているものの違いは何か？
- すべての違いを記載する（小さいものでも）
- 「それは問題ではあり得ない」と仮定しない
依存関係を理解する
- 他にどのコンポーネントが必要か？
- どのような設定、環境が必要か？
- どのような仮定をしているか？

Phase 3：仮説とテスト

科学的手法：

単一の仮説を立てる
- 明確に述べる：「Y という理由で X が根本原因だと思う」
- 書き留める
- 曖昧でなく、具体的に
最小限でテストする
- 仮説をテストするための最小限の変更を加える
- 一度に 1 つの変数
- 複数のことを一度に修正しない
続行する前に検証する
- 機能したか？はい → Phase 4
- 機能しなかったか？新しい仮説を立てる
- さらに修正を重ねない
理解していない場合
- 「X を理解していない」と言う
- 知っているふりをしない
- 助けを求める
- さらに調査する

Phase 4：実装

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

失敗するテストケースを作成する
- 最も単純な再現
- 可能ならば自動テスト
- フレームワークがない場合は使い捨てのテストスクリプト
- 修正する前に必須
単一の修正を実装する
- 特定された根本原因に対処する
- 一度に 1 つの変更
- 「ついでに」改善なし
- バンドルされたリファクタリングなし
修正を検証する
- テストは通るか？
- 他のテストは壊れていないか？
- 問題は実際に解決されたか？
- verification-before-completion スキルを使用する
修正が機能しない場合
- 停止
- いくつの修正を試したかカウントする
- 3 未満の場合：Phase 1 に戻り、新しい情報で再分析する
- 3 以上の場合：停止してアーキテクチャに疑問を持つ（下記 5 を参照）
- アーキテクチャについての議論なしに Fix #4 を試みない
3 以上の修正が失敗した場合：アーキテクチャに疑問を持つ

アーキテクチャ問題を示すパターン：
- 各修正が異なる場所で新しい共有状態/結合/問題を明らかにする
- 修正には「大規模なリファクタリング」が必要
- 各修正が他の場所で新しい症状を生み出す
停止して基本を疑問視する：
- このパターンは根本的に健全か？
- 「純粋な慣性で続けている」のではないか？
- 症状の修正を続けるのではなく、アーキテクチャをリファクタリングすべきか？
さらに修正を試みる前にユーザーと議論する

赤旗 - 停止してプロセスに従う

以下のことを考えていることに気付いたら：

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

これらはすべて以下を意味します：停止。Phase 1 に戻ります。

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

間違った実施を示すユーザーの信号

以下のリダイレクトに注意してください：

「それは起こっていないのですか？」 - 検証なしに仮定しました
「それは何を表示しますか？」 - 証拠収集を追加すべきでした
「推測をやめる」 - 理解せずに修正を提案しています
「これを徹底的に考えます」 - 症状だけでなく基本に疑問を持つ
「立ち往生しましたか？」（不満） - アプローチが機能していません

これらが見られたら：停止。Phase 1 に戻ります。

一般的な言い訳

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

クイックリファレンス

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

他のスキルとの統合

このスキルは以下と組み合わせます：

verification-before-completion - バグが解決したと主張する前に修正が機能したことを検証
brainstorming - 3 以上の修正が失敗した場合、設計の見直しが必要な場合がある

実世界への影響

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

体系的なアプローチ：15～30 分で修正
無計画な修正アプローチ：2～3 時間の試行錯誤
初回修正率：95% vs 40%
導入された新規バグ：ほぼゼロ vs 一般的

ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ

systematic-debugging

SKILL.md 本文