systematic-debugging

系統的なデバッグ

スラッシュコマンドの使用方法

/superpowers:systematic-debugging "<symptom>" を使って呼び出すか、バグ修正に関する表現が検出されたときに、ほかのスキルによって自動的に読み込まれます。

スラッシュコマンドとして呼び出す場合：$ARGUMENTS を症状の説明として取得し、直ちにフェーズ 1 を開始してください。設計ドキュメントやタスクファイルは作成しないでください。成果物は「修正と、回帰を検出するテスト」であり、docs/plans/ フォルダーではありません。

出力のルール：各フェーズを完了したら、その結果をインラインで報告してください。最後に、（a）根本原因を一文で、（b）修正差分の概要、（c）回帰テストのパスを示してください。

推奨：/goal でラップして実行する

マルチターンの仮説 → テスト → 修正の調査を、回帰が実際に修正されるまで続けられるよう、Claude Code 組み込みの /goal（v2.1.139 以降）の下で起動してください。

/goal "Claude has narrated the three-part completion output (root-cause one-liner, fix diff summary, regression-test path) with the regression test passing" /superpowers:systematic-debugging "<symptom>"

/goal はユーザーが入力する外側のラッパーです（スキルは実行途中に自分自身に対して有効化できません）。また、その評価対象は Claude がトランスクリプト内で説明した内容だけです。条件は、ファイルシステムの状態ではなく、説明された出力（表示されたテスト実行結果、3 部構成の要約）に基づいて記述してください。詳しい仕様と条件の記述方法については、../../skills/references/goal-wrapper.md を参照してください。

重要：打ち切りチェック（フェーズ 1 の前に実行）

$ARGUMENTS に「特定された根本原因と、特定された修正」を示す情報があるか確認してください。次の条件がすべて当てはまる場合は打ち切り、4 フェーズの手順を省略して、修正を適用し、回帰テストを直接作成してください。

• $ARGUMENTS に具体的な根本原因（ファイルと行番号、設定キー、または特定の値）が示されている、かつ
• $ARGUMENTS に具体的な修正内容（「X を Y に変更する」「不足しているフラグを追加する」「誤記を修正する」）が示されている、かつ
• 修正が単一のファイルまたは単一の文字列置換に限定されている

打ち切りとなる例：

• 「cookie domain が .foo.com になっているが、foo.com にするべきなので修正する」
• 「api.ts:42 に await がないので追加する」
• 「deploy.yaml の環境変数名 DB_HOST が誤っているので、DATABASE_HOST にする」

打ち切りとならない例（フェーズ 1 に進む）：

• 「CI ではテストが失敗するが、ローカルでは成功する」（症状のみで、根本原因がない）
• 「遅い」（仮説がない）
• 「キャッシュが原因だと思うので、確認してもらえますか？」（根本原因が確認されていない仮説）

打ち切り時の応答（以下をそのまま出力してから、修正を適用し、バグを検出する回帰テストを作成してください）：

特定された根本原因と修正を検出しました。4 フェーズの手順（根本原因が不明な場合に適用）を省略します。修正を適用し、回帰テストを直接作成します。完全な手順を強制するには、/superpowers:systematic-debugging --force "<symptom>" として再度呼び出してください。

ユーザーが --force（$ARGUMENTS 内のリテラルトークン）を指定した場合は、この打ち切りを省略し、必ずフェーズ 1 に進んでください。

打ち切りとならない場合は、引き続き鉄則に従います。打ち切りは、ユーザーがすでに根本原因を特定し、その結論を Claude に伝えている場合にのみ適用されます。

概要

基本原則： 修正を試みる前に、根本原因を調査する必要があります。場当たり的な修正は時間を浪費し、根本的な問題を覆い隠し、新たなバグを生みます。このプロセスを字義どおりに守らないことは、デバッグの精神に反することです。

重要：鉄則

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

フェーズ 1 を完了する前に、修正を提案してはいけません。次のフェーズに進む前に、各フェーズを必ず完了してください。このルールに違反すると、根本原因を覆い隠す修正を試みることになります。それこそ、このスキルが防ごうとしている失敗パターンです。フェーズ 1 の証拠がそろう前に修正を提案しようとしていると気づいたら、いったん止めてフェーズ 1 に戻ってください。

適用する場面

あらゆる技術的な問題に適用します。テストの失敗、本番環境のバグ、予期しない動作、パフォーマンスの問題、ビルドの失敗が対象です。

特に有効な場面： 時間に追われて推測したくなるとき、「手早い修正」が明白に思えるとき、これまでの修正が失敗したとき、または問題を十分に理解できていないときです。

問題が単純に見える場合、時間がない場合、または緊急の場合も、このプロセスを省略しないでください。それぞれがなぜ落とし穴なのかについては、./references/rationalizations-and-guardrails.md を参照してください。

4 つのフェーズ

フェーズ 1：根本原因の調査

修正を試みる前に：

0. メモリを参照する — Bail-Out Check が発動した場合、このメモリ読み取りのステップはスキップされます（Bail-Out Check がフェーズ 1 以降の他のすべてのステップをスキップするのと対称的です）。bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active を実行し、症状に関するキーワードで絞り込み、上位 2～3 件を手順 1 の前に読みます。

1. エラーメッセージを注意深く読む — スタックトレースを最後まで読み、行番号、ファイルパス、エラーコードを記録します。メッセージや警告に解決策が含まれていることもよくあります。

2. 再現性を確認する — 正確な手順を特定し、問題が確実に発生することを確認します。再現できない場合は、推測せずにさらにデータを集めます。

3. 最近の変更を確認する — git diff と最近のコミット、新しい依存関係、設定の変更、環境の違いを確認します。

4. 複数コンポーネントから成るシステムの証拠を集める（CI → ビルド → 署名、API → サービス → データベース）— 修正を提案する前に、診断用の計測を追加します：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   実例（CI ワークフロー → ビルド → 署名）：./references/root-cause-tracing.md §Multi-Layer Instrumentation Example。

5. データフローをたどる — コールスタックの深い箇所でエラーが発生している場合、問題のある値の発生箇所を特定し、何がその処理を呼び出したかを調べ、発生源が見つかるまで上流へたどります。症状ではなく、発生源を修正します。逆方向にたどる手法の全容は、./references/root-cause-tracing.md を参照してください。

フェーズ 2：パターン分析

修正の前に、パターンを特定します：

1. 動作する例を見つける — 同じコードベース内で、類似した動作するコードを探します。
2. リファレンスと比較する — パターンを実装する場合は、適用する前にリファレンス実装をすべて読みます（流し読みせず、1 行ずつ読みます）。
3. 違いを特定する — 動作するコードと壊れているコードの違いをすべて列挙します。小さな違いを無関係だと決めつけないでください。
4. 依存関係を理解する — この処理に必要な他のコンポーネント、設定、構成、環境、パターンが前提としている条件を確認します。

フェーズ 3：仮説と検証

科学的手法の適用：

1. 単一の仮説を立てる — 「Y であるため、根本原因は X です」のように、明確かつ具体的に述べます。
2. 最小限のテストを行う — 可能な限り小さく変更し、一度に 1 つの変数だけを変えます。複数の問題を同時に修正しないでください。
3. 続行する前に検証する — 確認できた場合はフェーズ 4 に進みます。確認できなかった場合は、新しい仮説を立てます。さらに修正を重ねてはいけません。
4. 理解が不足している場合 — そのことを認め、さらに調査するか、助けを求めます。

フェーズ 4：実装

症状ではなく、根本原因を修正します。

1. 失敗するテストケースを作成する — 可能な限りシンプルに再現します。可能であれば自動テストを作成し、テストフレームワークがない場合は単発のスクリプトを使用します。修正する前にテストを用意してください。

2. 修正を1つだけ実装する — 特定した根本原因に対処し、一度に1つずつ変更します。「ついでに」行う改善や、修正に便乗したリファクタリングはしないでください。

3. 修正を検証する — テストは通りましたか？ ほかのテストは失敗していませんか？ 問題は実際に解決しましたか？

4. 修正がうまくいかない場合 — 作業を止め、試した修正の数を数えます。3回未満なら、フェーズ 1 に戻り、新たに得られた情報をもとに再分析します。3回以上なら、アーキテクチャを問い直します。

5. 修正に3回以上失敗した後のアーキテクチャの再検討 — 修正のたびに別の場所で共有状態や結合の問題が明らかになる、「大規模なリファクタリング」が必要になる、または新たな症状が生じる場合は、作業を止めて基本から問い直します。このパターンは妥当でしょうか？ 慣性でこのアプローチを続けていませんか？ 症状を修正するのではなく、アーキテクチャをリファクタリングすべきではありませんか？ さらに修正を試みる前に、人間のパートナーと相談してください。これは仮説が外れたのではなく、アーキテクチャが誤っているということです。

6. メモリーを記録する（条件付き — このスキルが docs/ に触れる唯一の箇所であり、新しいフェーズやコミットではありません）

   この手順では、既存の「修正に3回以上失敗した場合」というトリガーを主な判定条件として再利用します。このトリガーが発火した場合は、修正と同じコミットでメモリーの upsert を実行します。また、修正を試した回数に関係なく、横断的に影響する明示的な落とし穴があれば、独立して発火します。それ以外の場合は何もしません。

   発火した場合は、docs/memory/<category>_<slug>.md に記録します（通常、category は pitfall。アーキテクチャの再検討で再設計が結論となった場合は decision）。インラインプランの6行形式を Fact／Why の記述に再利用し、source: commit:<short-sha> を指定します。次に bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category <category> を実行し、修正および回帰テストと同じコミットにステージします。別のコミットにしたり、成果物を追加したりしないでください。

複雑なバグ：インラインプランの要約（ファイルは作成しません）

複雑なバグの場合は、コードを変更する前に、コンパクトなプランをインラインで記録します。docs/plans/ フォルダーや BUGFIX_PLAN.md ファイルは決して作成しないでください（理由：./references/rationalizations-and-guardrails.md §複雑なバグのプランをインラインにする理由）。インラインプランは、フェーズ 2～4 でスキルが遵守する契約であり、修正後にユーザーが確認する監査対象です。

インラインプランが必要な場合

次のいずれかに該当するバグでは、編集前にインラインプランの手順が必要です。複数のファイル、モジュール、サブシステムが関係する場合、アーキテクチャに影響する場合（設計、契約、インターフェース）、有効なアプローチが複数ある場合、無関係な機能に副作用が及ぶリスクがある場合、最小限のパッチを超えるリファクタリングが必要な場合、またはフェーズ 1 の後も根本原因が明確でない場合です。

インラインプランの形式

フェーズ 1（根本原因の調査）の後、次の6行形式を使って、プランをファイルではなく、自分のターンの出力にインラインで記録し、そのプランを契約としてフェーズ 2 に直接進みます。

ROOT CAUSE: <one-line summary from Phase 1 evidence>
FIX STRATEGY: <what change resolves the cause, in one sentence>
FILES: <comma-separated paths that will be modified>
TESTS: <regression test path(s) + scenario name>
RISKS: <one line — side effects, blast radius, or "low: localized to <subsystem>">
ALTERNATIVES: <one line — rejected approaches + why>

承認を求めて作業を中断してはいけません。このプランはフェーズ 2～4 を通じて契約として維持します。プランから逸脱する場合は、フェーズ 1 を再実行し、新しい6行形式を記録してください。作業の途中で、何も記録せずに修正内容を変えてはいけません。証拠が不十分で自信を持って記入できない行がある場合は、まずフェーズ 1 のステップ 4 に戻ってください。曖昧な記述で根拠の弱さを取り繕ってはいけません。

単純なバグの場合： インラインプランは不要です。そのままフェーズ 2～4 に進みます。

危険信号

次のような思考パターンは、プロセスに違反していることを示しています。フェーズ 1 に戻ってください。

• 「とりあえず応急処置をして、後で調査しよう」
• 「X を変えて、うまくいくか試してみよう」
• 「複数の変更を加えて、テストを実行しよう」
• 「テストは省略して、手動で確認しよう」
• 「おそらく X だから、修正してみよう」
• 「完全には理解していないが、これでうまくいくかもしれない」
• 「パターンでは X とされているが、別の方法に変えてみよう」
• データフローを追跡する前に解決策を提案する
• 「もう一度修正を試そう」（すでに 2 回以上試している場合）
• 修正のたびに、別の箇所で新たな問題が見つかる

修正に 3 回以上失敗した場合： アーキテクチャを疑ってください。

人間のパートナーから軌道修正された場合（「それは起きていないのでは？」「当てずっぽうはやめて」「行き詰まっているのでは？」）：フェーズ 1 に戻ってください。シグナルの全リストに加え、上記のすべての正当化についての言い訳と実態の対照表は ./references/rationalizations-and-guardrails.md を参照してください。

クイックリファレンス

フェーズ	主な活動	成功基準
1. 根本原因	エラーを読み、再現し、変更を確認し、証拠を集める	何が、なぜ起きているかを理解する
2. パターン	動作する例を見つけ、比較する	相違点を特定する
3. 仮説	理論を立て、最小限のテストを行う	仮説を確認するか、新たな仮説を立てる
4. 実装	テストを作成し、修正して検証する	バグが解決し、テストに合格する

プロセスを通じても根本原因が見つからない場合

体系的な調査の結果、問題が環境依存、タイミング依存、または外部要因によるものだと判明した場合、プロセスは完了です。調査した内容を記録し、適切な対処（再試行、タイムアウト、エラーメッセージ）を実装し、今後の調査に備えて監視とログ記録を追加してください。注： 根本原因が見つからないケースの 95% は、調査が不十分であることを示しています。

参考資料

• ./references/root-cause-tracing.md - 遡及的な追跡、複数レイヤーにわたる計測の例
• ./references/rationalizations-and-guardrails.md - 言い訳の対照表、パートナーのシグナル、インライン計画の根拠、影響に関する数値
• ./references/defense-in-depth.md - 根本原因の特定後、複数のレイヤーに検証を追加する
• ./references/condition-based-waiting.md - 任意のタイムアウトを条件ポーリングに置き換える（例：condition-based-waiting-example.ts）
• ./find-polluter.sh - テストスイートを二分探索し、共有状態を汚染するテストを特定する
• ../../skills/references/goal-wrapper.md - /goal のセマンティクスと条件の表現（共有）

関連スキル：

• superpowers:behavior-driven-development - テスト設計のための Gherkin シナリオを含む BDD の原則