systematic-debugging について
開発者向けのデバッグスキルで、段階ごとの条件を設けた4フェーズで原因を調べてからコードを変更します。再現可能な証拠と検証可能な仮説を重視し、原因が絞れない場合は設計も見直します。
主な機能
- 01エラー、再現手順、環境情報の収集
- 02正常ケースと失敗ケースの比較
- 03証拠に基づく仮説の個別検証
- 04仮説が外れた場合の設計見直し
- 05根本原因を把握してから修正
活用シーン
- 01再現可能なソフトウェア障害の調査
- 02問題を最小の再現例に絞り込む
- 03障害の背景にある環境差の確認
- 04仮説が続けて外れた後の設計再評価
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/systematic-debuggingを入力して読み込まれたか確認します。
同梱ファイルdefense-in-depth.mdroot-cause-tracing.md
詳細
系統的なデバッグ
概要
デバッグは実験ではなく、調査です。このスキルでは、根本原因の調査、パターン分析、仮説検証、アーキテクチャの見直しという厳密な4段階のプロセスを徹底します。これにより、手当たり次第のデバッグを防ぎ、修正を適用する前にその内容を確実に理解できます。
開始時に宣言します：「この問題を調査するため、系統的なデバッグスキルを使用します。」
基本原則
┌─────────────────────────────────────────────────────────────────┐
│ HARD-GATE: NEVER GUESS. NEVER SHOTGUN DEBUG. │
│ NEVER CHANGE CODE WITHOUT UNDERSTANDING WHY IT IS BROKEN. │
│ │
│ You are a detective gathering evidence, not a gambler trying │
│ random fixes. If you are changing code without understanding │
│ the root cause, STOP immediately. │
└─────────────────────────────────────────────────────────────────┘
フェーズ1：根本原因の調査
目標： 何が起きているのかを正確に把握します。何が起きていると思うかではありません。
実施項目
- エラーメッセージを注意深く読みます。 メッセージ全体を読みます。すべての行を確認します。スタックトレースも含みます。
- バグを再現します。 再現できなければ修正できません。正確な手順を見つけます。
- 証拠を集めます。 次の情報を収集します。
- エラーメッセージとスタックトレースの全体
- バグを引き起こす入力
- 期待される動作と実際の動作
- 環境の詳細（バージョン、設定、OS）
- 最近の変更を確認します。 最後に正常に動作したときから何が変わりましたか？
- 最近のコミット（
git log、git diff） - 依存関係の更新
- 設定の変更
- 環境の変更
- 最近のコミット（
証拠収集チェックリスト
- エラーメッセージ全体を取得済み（途中で切れていない）
- スタックトレースを下から上へ確認済み
- 特定の手順でバグを安定して再現済み
- 期待される動作と実際の動作を記録済み
- 最近の変更を確認済み（
git log --oneline -20） - 関連するログを確認済み
停止 — 厳格な条件：以下を満たすまでフェーズ2に進まないでください
- バグを一貫して再現できる
- エラーメッセージとスタックトレースの全体を確認している
- 最近何が変わったか把握している
- バグを正確に説明できる（曖昧ではない）
フェーズ2：パターン分析
目標： 問題がどこにあり、いつ発生するのかを絞り込みます。
実施項目
- 正常に動作する例を探します。 この機能は、ほかの状況や入力、環境では動作しますか？
- 正常なケースと壊れているケースを比較します。 動作するケースと動作しないケースには、どのような違いがありますか？
- 依存関係を確認します。 必要なサービス、ライブラリ、設定はすべて揃っており、正しく設定されていますか？
- 範囲を絞り込みます。 最小限の例で再現できますか？ 不要なものをすべて取り除きます。
比較マトリクス
パターンを特定するために、次の表に記入します。
| 要素 | 正常なケース | 問題のあるケース | 違いがあるか |
|---|---|---|---|
| 入力データ | |||
| 環境 | |||
| 設定 | |||
| 依存関係 | |||
| タイミング／順序 | |||
| ユーザー／権限 | |||
| 状態／コンテキスト |
停止 — 厳格な条件：以下を満たすまでフェーズ3に進まないでください
- 比較対象となる正常なケースを少なくとも1つ特定している
- 正常なケースと問題のあるケースを比較し、違いを特定している
- 再現可能な最小のケースまで範囲を絞り込んでいる
- 依存関係（バージョン、利用可能性、設定）を確認済み
フェーズ3：仮説と検証
目標： 具体的で検証可能な仮説を1つ立て、可能な限り小さな変更で検証します。
実施項目
- 仮説を1つ立てます。 フェーズ1～2で得た証拠に基づき、最も可能性の高い原因は何ですか？
- 明確に述べます：「このバグは、[具体的な原因]によって発生する」
- 具体的に述べられない場合は、フェーズ1または2に戻ります
- 最小限のテストを設計します。 この仮説を検証または否定するために、どのような最小の変更が必要ですか？
- 本番コードを変更するより、テストケースの追加を優先します
- コード変更より、ログやアサーションを優先します
- 新しいコードを書くより、変更を元に戻すことを優先します
- 変更を適用してテストします。
- 仮説の検証に必要な変更だけを行います
- テストスイートを実行します
- 結果を観察します
- 評価します。
- 確認できた場合：修正に進み、リグレッションテストを書きます
- 否定された場合：学んだことを記録し、新しい仮説を立てて、手順1に戻ります
仮説ログのテンプレート
Hypothesis #1: [description]
Test: [what you did]
Result: CONFIRMED / DENIED
Learning: [what this taught you]
Hypothesis #2: ...
判断表：仮説検証のアプローチ
| 仮説の種類 | 検証方法 | 例 |
|---|---|---|
| 最近のコード変更が原因 | git bisect またはコミットの取り消し | 「コミット abc123 でバグが混入した」 |
| データ形状の不一致 | ログまたはアサーションを追加 | 「API が配列ではなく null を返す」 |
| 競合状態 | タイミングログを追加するか、直列化する | 「リクエスト A より先にリクエスト B が完了する」 |
| 設定エラー | 環境間で設定を比較する | 「本番環境では異なる DB ホストが使われている」 |
| 依存関係のバージョンの問題 | 確実に動作するバージョンに固定する | 「ライブラリ 2.0 で API の仕様が変更された」 |
停止 — 必須条件：以下を満たさない限り、フェーズ 4 に進まないでください：
- 少なくとも 3 つの仮説を検証し、すべて否定した
- 各仮説が具体的で検証可能だった
- 各テストが最小限だった（一度に変更するのは 1 つだけ）
- 否定された各仮説から得た知見を記録した
フェーズ 4：アーキテクチャへの問いかけ
目標： 3 つ以上の仮説が失敗した場合、問題は構造的なものかもしれません。一歩下がって、前提を問い直してください。
このフェーズは、フェーズ 3 を少なくとも 3 回試しても成功しなかった場合にのみ開始します。
アクション
- 前提を問い直してください。 真実だと思い込んでいることのうち、そうでない可能性があるものは何ですか？
- データの形状は、想定どおりですか？
- 制御フローは、期待どおりですか？
- 型は、想定どおりですか？
- API コントラクトは、想定したとおりですか？
- 設計を問い直してください。 現在のアプローチに根本的な欠陥はありませんか？
- 設計に競合状態はありませんか？
- 状態管理に問題はありませんか？
- 抽象化が誤っていませんか？
- 責務の割り当てが適切ではありませんか？
- 再設計を検討してください。 修正ではなく、構造の見直しが必要な場合もあります。
- バグのクラス全体をなくすよう、設計を簡素化できますか？
- このケースをより適切に処理するパターンはありますか？
- 修正するのではなく、置き換えるべきですか？
- 外部の意見を求めてください。 行き詰まった場合：
- 他の人に問題を説明します（ラバーダックデバッグ）
- 依存関係に既知の問題がないか検索します
- 同様の問題に遭遇した人がいないか確認します
停止 — 必須条件：以下を満たさない限り、先に進まないでください：
- 問い直した前提を記したリスト
- 明確な決定：現在の設計を修正する、または再設計する
- 再設計する場合：実装前の計画
- 修正する場合：前提の見直しを踏まえた新しい仮説
デバッグの判断フローチャート
Error encountered
|
v
Can you reproduce it?
|
+-- NO --> Gather more information (logs, user reports, monitoring)
| Try different inputs, environments, timing
| Do NOT proceed until reproducible
|
+-- YES -> Read the FULL error message and stack trace
|
v
Is the cause obvious from the error?
|
+-- YES -> Form hypothesis, test it (Phase 3)
| Still write a regression test
|
+-- NO --> Complete Phase 1 evidence gathering
|
v
Find working case for comparison (Phase 2)
|
v
Identify differences
|
v
Form and test hypotheses (Phase 3)
|
+-- Fixed --> Write regression test, verify
|
+-- 3+ failed hypotheses --> Phase 4
危険信号の表
| 危険信号 | 意味 | 対処 |
|---|---|---|
| バグを理解せずにコードを変更する | 手当たり次第のデバッグ | フェーズ 1 に戻る |
| 修正できたが理由がわからない | 偶然の修正で、再発する可能性が高い | 理解できるまで調査する |
| 同じバグが繰り返し発生する | 根本原因に対処できていない | フェーズ 4 に進み、設計を問い直す |
| 修正によって別の場所に新たなバグが発生する | 想定外の結合 | 先に進む前に依存関係を図示する |
| 「自分のマシンでは動く」 | 環境の違い | フェーズ 2 に進み、比較マトリックスを確認する |
| 修正に 20 行を超えるコードが必要 | 設計上の問題かもしれない | フェーズ 4 に進む |
| デバッグが 30 分以上続いている | 視野狭窄 | 休憩し、フェーズ 1 の証拠を読み直す |
| 同じコードを何度も読み返している | 根本的な何かを見落としている | 新しい視点を得て、声に出して説明する |
| 複数の原因が同じ程度にありそうに思える | 調査が不十分 | フェーズ 1 に戻り、さらに証拠を集める |
反パターン／よくある間違い
| 反パターン | なぜ間違っているのか | 正しいアプローチ |
|---|---|---|
| バグが解消するか確かめるために、手当たり次第に変更する | 時間を浪費し、新たなバグを引き起こします | まず仮説を立てます |
| エラーを抑えるために try/catch を追加する | 根本的な問題を隠してしまいます | 根本原因を修正します |
| 機能を一から書き直す | 最終手段が必要になることはほとんどありません | 問題を特定して修正します |
| 証拠もなくフレームワーク／ライブラリのせいにする | 通常はコードに問題があります | 最小限の再現コードで、フレームワークのバグを証明します |
| 修正後に回帰テストを省略する | バグが再発します | 必ずテストを書きます |
| 根本原因ではなく症状を修正する | パッチが積み重なり、システムが劣化します | 実際の原因を突き止めます |
| 一度立ち止まらずに45分以上デバッグを続ける | 視野が狭まり、効果が下がります | 休憩を取り、フェーズ1の証拠を読み直します |
| エラーメッセージやスタックトレースを無視する | 解決の手がかりは、多くの場合エラーにあります | エラーのすべての行を読みます |
統合ポイント
| スキル | 関係 |
|---|---|
test-driven-development | すべてのバグ修正には、必ず回帰テストを含めます（RED-GREEN サイクル） |
verification-before-completion | バグを修正した後、新たな証拠を使って検証します |
resilient-execution | タスクの実行中にデバッグする場合は、タスクを一時停止し、デバッグを完了してから再開します |
code-review | 修正の完全性と副作用をレビューします |
self-learning | 新たなデバッグパターンを learned-patterns.md に記録します |
acceptance-testing | 修正によって受け入れ基準が損なわれないことを検証します |
クイックリファレンス：してはいけないこと
- してはいけません：バグが解消するか確かめるために、手当たり次第に変更する
- してはいけません：エラーを抑えるために try/catch を追加する
- してはいけません：最初の手段として機能を一から書き直す
- してはいけません：証拠もなくフレームワーク／ライブラリのせいにする
- してはいけません：修正後に回帰テストを書くことを省略する
- してはいけません：根本原因ではなく症状を修正する
- してはいけません：一度立ち止まらずに45分を超えてデバッグを続ける
- してはいけません：エラーメッセージやスタックトレースを無視する
スキルの種類
RIGID — 4フェーズのプロセスは必須であり、順番どおりに実行する必要があります。次に進む前に、各フェーズのハードゲートを満たさなければなりません。なぜ壊れているのかを理解せずに、コードを変更してはいけません。
コメント
Markdown 対応