systematic-debugging

systematic-debugging skill の概要

systematic-debugging skill は、場当たり的な修正を減らし、根本原因までより速くたどり着くための、エージェントや開発者向けの構造化デバッグワークフローです。中核となるルールはシンプルで、コードを変える前に調査すること。だからこそ、テスト失敗、フレークする挙動、本番障害、ビルド不具合、連携まわりの問題など、「とりあえずの修正」がかえって本質を隠しやすいケースに向いています。

この skill が特に向いている人

次のような場面なら systematic-debugging を使う価値があります。

• 修正しても失敗したり、中途半端にしか直らなかったりする
• 時間に追われながらデバッグしている
• AI アシスタントに、症状だけをつぎはぎで直すのではなく、いったん立ち止まって調べてほしい
• バグ、フレークテスト、想定外の挙動に対して再現性のある手順がほしい

特に、問題が一見わかりやすそうなのに、「なぜ起きるのか」はまだ説明できないときに有効です。

この skill が実際に助けてくれる仕事

本当にやるべきことは、単に「修正を作る」ことではありません。やるべきなのは次の順番です。

1. 問題を再現する
2. 原因を追跡する
3. 仮説を一つずつ検証する
4. その後で、狙いを絞った修正を実装する

一見すると遠回りですが、実際には手戻り、外れたパッチ、推測で入れたことで増える新たなバグを減らしやすくなります。

systematic-debugging が他と違う理由

一般的なプロンプトは、症状からすぐ解決策に飛びがちです。systematic-debugging skill は、そこをあえて許しません。リポジトリ全体としても、「まず根本原因を調べる。原因がわかる前に直さない」という “Iron Law” 的な進め方が強く打ち出されています。

さらに、周辺ファイルがあることで、単なる汎用デバッグチェックリストより実践的になっています。

• root-cause-tracing.md は、見えているエラー箇所と本当の発生源が離れているときに役立つ
• condition-based-waiting.md は、適当な待機時間が原因の flaky な async テストに効く
• defense-in-depth.md は、その場しのぎのバリデーション修正を、再発防止まで含む設計に引き上げる助けになる
• find-polluter.sh は、ファイルや状態を汚染するテストの切り分けに使える

向いている問題の種類

systematic-debugging for Debugging が特にハマるのは、次のようなケースです。

• まだ原因を説明できないテスト失敗
• CI 上で発生する flaky test
• 以前の修正が定着しなかったバグ
• スタックの深い場所で表面化するエラー
• 不正な状態、ファイルリーク、パス違い、race condition、タイミング起因の不具合

向いていないケース

次のように、そもそもデバッグ作業ではないタスクなら、優先度は下がります。

• まっすぐ進められる機能追加
• 説明すべき失敗挙動のない、定型的なリファクタリング
• 見た目だけの変更

とはいえ、「想定外の挙動に対応している」のであれば、systematic-debugging から始めるほうがたいてい安全です。

systematic-debugging skill の使い方

systematic-debugging の導入方法

このエコシステムで共通の Skills CLI パターンを使っているなら、インストールは次のとおりです。

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

その後は、エージェント環境から呼び出すか、skill フォルダ内のソースファイルを読んで手順をそのまま使います。

まず読むべきファイル

短時間で要点をつかむ systematic-debugging guide としては、次の順で読むのが効率的です。

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

この順番をおすすめする理由:

• SKILL.md で必須の 4 フェーズワークフローを把握できる
• root-cause-tracing.md は、症状がかなり下流に出ているケースで効く
• condition-based-waiting.md は、flaky な async テストに対する具体的な修正パターンを示してくれる
• defense-in-depth.md は、最終的な修正をより堅くする助けになる
• find-polluter.sh は、テスト汚染を切り分ける実用ツールとしてそのまま使える

この skill に渡すべき入力

systematic-debugging usage の質は、渡す材料の質にかなり左右されます。少なくとも次はそろえてください。

• 正確なエラーメッセージ
• スタックトレース
• 再現手順
• 期待動作と実際の動作
• OS、runtime、test runner、CI のみかローカルのみか、といった環境情報
• 最近のコード変更
• 問題が毎回起きるのか、flaky なのか
• すでに試したこと

これらがないと、モデルは推測に寄りやすくなります。

粗いバグ報告を、強いプロンプトに変える

弱いプロンプト:

Test is failing. Help fix it.

より強いプロンプト:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

この書き方がよいのは、実装より先に調査結果を出させる構造になっているからです。

実務で使いやすいプロンプトテンプレート

systematic-debugging usage では、次の構成で渡すと扱いやすくなります。

• Issue: 何が失敗したか
• Reproduction: 正確なコマンドまたは再現手順
• Evidence: ログ、トレース、スクリーンショット、失敗したアサーション
• Scope: ローカルだけか、CI だけか、特定端末だけか、全環境か
• Recent changes: コミット、依存更新、設定変更
• Constraints: API は変えられない、最小パッチが必要、締切がある、など
• Request: まず根本原因を調べ、その後に修正を 1 つ提案してほしい

例:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

4 フェーズのワークフローを順番どおりに進める

このリポジトリは 4 つのフェーズを中心に組まれています。実運用では、次のように使うのが基本です。

1. Root cause investigation
   エラーを丁寧に読み、安定して再現し、何が変わったかを確認し、証拠を集める。
2. Pattern analysis
   タイミング、環境差、入力形状、状態リーク、呼び出し連鎖といったパターンを探す。
3. Hypothesis testing
   仮説は一度に一つずつ立てて検証する。複数の変数を同時に変えない。
4. Implementation
   証拠が原因を支えてから、修正を入れて検証する。

Phase 1 が弱いと、その後の工程はすべて精度が落ちます。

flaky test に systematic-debugging を使う方法

この点は、このリポジトリの強みがかなりはっきりしています。テストが sleep、setTimeout、あるいは根拠の薄い待機時間に依存しているなら、condition-based-waiting.md と condition-based-waiting-example.ts をまず確認してください。

重要なのは、次の発想の切り替えです。

• 悪いパターン: 非同期処理に何ミリ秒かかるかを勘で決める
• よいパターン: 完了したと判断できる条件が成立するまで待つ

多くの「ランダムな失敗」は、実際にはタイミングの推測で隠れている race condition です。

症状が下流に出ているときの使い方

エラーがスタックの深い場所で発生していたり、不正なデータが入った地点からかなり離れたところで表面化していたりするなら、root-cause-tracing.md を使います。流れは次のとおりです。

• まず直近で失敗している行を特定する
• 呼び出し元を 1 段ずつたどる
• 不正な状態が最初に現れた地点まで追跡する
• 落ちた場所だけでなく、発生源で直す

これは systematic-debugging skill の中でも特に価値の高い部分で、多くのバグが「その場のクラッシュ」ではなく、もっと前段の不正状態の結果だからです。

polluter finder の使い方

ファイル、ディレクトリ、状態をテストが後始末せず残してしまう場合は、自己流でループを書く前に find-polluter.sh を読む価値があります。

利用パターン:
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

スクリプト内の例:
./find-polluter.sh '.git' 'src/**/*.test.ts'

目に見えて失敗しているテストそのものではなく、別のテストによる汚染が原因のときに役立ちます。

最も結果が出やすい実践フロー

systematic-debugging install 後の初回利用まで含めて、安定して使いやすい流れは次のとおりです。

1. skill をインストールする
2. SKILL.md を読む
3. 失敗の証拠を正確に集める
4. 修正ではなく調査をエージェントに依頼する
5. 証拠が最も強い仮説を選ぶ
6. その仮説だけを検証する
7. 焦点の絞れた修正を 1 つ実装する
8. 問題の原因が不正データや複数の流入経路にあるなら、validation や defense-in-depth を追加する

これで最もありがちな失敗、つまり「何が起きたか理解する前にコードを変える」ことを防げます。

この skill でやるべきでないこと

systematic-debugging に次のような依頼は向きません。

• 最初から大量の修正案をブレストさせる
• バグ再現前に広い範囲を書き換えさせる
• 説明なしに「とにかくテストを通して」と頼む
• 疑わしい原因をいくつも同時にパッチする

こうした近道は、この skill の設計思想と正面からぶつかり、出力品質も落ちやすくなります。

systematic-debugging skill の FAQ

systematic-debugging は複雑なバグ専用ですか？

いいえ。このリポジトリの立場では、単純に見えるバグにも根本原因はあります。むしろ、簡単そうに見えて雑にパッチを当てたくなる問題ほど、この skill の価値が出ます。

普通のデバッグ用プロンプトと何が違いますか？

普通のプロンプトは、速さや推測ベースの修正を促しがちです。systematic-debugging は、調査・仮説・実装を明確に分けることを求めます。その結果、外れたパッチが減り、説明の質も上がりやすくなります。

systematic-debugging は初心者でも使えますか？

はい。具体的な証拠を出せるなら、十分使えます。プロセス自体は厳密ですが、やることはわかりやすく、再現して、観察して、追跡して、仮説を 1 つ検証してから直す、という流れです。むしろ初心者ほど、行き当たりばったりの試行錯誤を避けられるぶん恩恵が大きい場合があります。

どんなときは systematic-debugging を使わないほうがいいですか？

次の用途を主目的にするなら、第一選択には向きません。

• 機能アイデア出し
• アーキテクチャのブレスト
• 失敗事象と無関係なコード生成
• 壊れた挙動の説明が不要な、純粋な見た目調整

何かがおかしくて、パッチだけでなく原因が必要なときに使うのが正解です。

CI でしか起きない失敗にも効きますか？

はい。systematic-debugging は、CI 限定の失敗や負荷依存の不具合と相性がよいです。環境差、再現条件、タイミング前提、状態前提を比較させる方向に導くため、勘で直しに行くよりずっと適しています。

flaky な async テストにも使えますか？

はい。そしてこのリポジトリは、その点で平均以上に実践的です。condition-based-waiting.md と TypeScript の例ファイルによって、適当な待ち時間から離れ、条件ベースの同期へ移る具体的な道筋が示されています。

この skill はツール込みですか、それとも助言だけですか？

中心はプロセスガイドですが、実用的な補助ファイルもいくつか含まれています。特に役立つのは find-polluter.sh で、condition-based waiting のサンプルも、一部の TypeScript テスト構成ではそのまま再利用しやすい内容です。

systematic-debugging はどのスタックでも使えますか？

概ね使えます。中核の方法論はスタック非依存です。例は TypeScript、shell、テストワークフロー寄りですが、調査の進め方自体は言語やフレームワークをまたいで有効です。

systematic-debugging skill を改善するには

修正を求める前に、よりよい証拠を渡す

いちばん効く改善ポイントは入力の質です。systematic-debugging の結果を良くしたいなら、少なくとも次を含めてください。

• 正確な再現コマンドを 1 つ
• 正確なエラーブロックを 1 つ
• 最小の失敗テストまたはファイルを 1 つ
• 最近何を変えたか
• 毎回再現するのかどうか

こうすると、この skill は推測ではなく証拠ベースで動きやすくなります。

実装の前に、調査結果の出力を求める

高品質なプロンプトは、早すぎる修正提案を明示的に止めています。たとえば次のように書けます。

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

症状を読んですぐコード編集に入るのではなく、間にチェックポイントを置けるため、回答の質が上がりやすくなります。

仮説は必ず一つずつ扱わせる

よくある失敗は、複数の原因候補を 1 つのパッチに混ぜてしまうことです。次の 3 点を出させると、流れを保ちやすくなります。

• 最有力の仮説
• その仮説を否定できる最小のテスト
• 何が出れば確認になったと言えるか

これで、ワークフローが skill 本来の意図からずれにくくなります。

flaky test 向けのプロンプトを改善する

flaky test に対して systematic-debugging for Debugging を使うときは、次も添えると効果的です。

• 成功／失敗の頻度
• parallel 実行や CI と相関があるか
• sleep、wait、retry、polling を使っているか
• テストが観測したい正確なイベントまたは状態

これがあると、モデルが condition-based-waiting.md を関連パターンとして判断しやすくなります。

SKILL.md だけでなく周辺ファイルも使う

最初の出力が抽象的すぎると感じたら、補助ドキュメントを明示的に参照させてください。

• root-cause-tracing.md は下流症状向け
• condition-based-waiting.md は timing / race issue 向け
• defense-in-depth.md は validation 戦略向け
• find-polluter.sh は test pollution 向け

この skill は、見出しのワークフローだけでなく、用途別の補助資料まで使ってこそ精度が上がります。

1 回目の結果が広すぎたら、スコープを絞る

最初の回答が大づかみすぎるなら、次の情報で絞り込みます。

• 正確に確認してほしいサブシステム
• 不正データが入りそうな境界
• 問題が現れ始めた最初のコミット
• 最小の失敗再現

広いデバッグ依頼は、広い調査計画を生みがちです。原因追跡の精度を上げたいなら、範囲を狭めるのが有効です。

診断だけでなく、最終修正の質も上げる

根本原因が見つかったあとには、次の 3 点まで依頼すると仕上がりがよくなります。

• 最小の修正
• 回帰テストを 1 つ
• 再発を防ぐ validation layer を 1 つ

ここで defense-in-depth.md が役立ちます。問題の発端が不正入力や、簡単にすり抜ける前提条件にあるなら、単発パッチだけでは足りないことがあります。

よくある失敗パターンに注意する

systematic-debugging usage がうまくいかない典型例は次のとおりです。

• エラーテキストが不完全
• 信頼できる再現手順がない
• 修正提案を早く求めすぎる
• テスト実行のたびに複数箇所を変える
• もっともらしい最初の説明を、そのまま事実扱いする

これらを避けるだけでも、この skill は単なる「これをデバッグして」プロンプトより、かなり価値の高いものになります。