Systematic Debugging（体系的デバッグ）

Systematic Debugging は、Jesse Vincent（GitHub: obra）が公開しているスキル集 Superpowers に含まれるデバッグ用のスキルです。SKILL.md の description は「バグ、テストの失敗、想定外の挙動に出会ったとき、修正を提案する前に使う」というもので、エージェントがこの種の場面に入ると自動で読み込まれます。

中心にあるのは「根本原因を調べる前に修正しない」という決まりです。原因調査、パターン分析、仮説と検証、実装という4つの段階を順に終えることを求め、修正を3回試してだめなら設計そのものを疑って人間と相談するよう指示しています。

Superpowers 全体は、設計の聞き取りから計画づくり、テスト駆動開発、サブエージェントでの実装、レビューまでをスキルで組み立てた開発手法です。このスキルはその中で、不具合対応を受け持ちます。

SKILL.md の構成

本文は「概要」「鉄則」「使う場面」「4つの段階」「危険信号」「人間側からの合図」「よくある言い訳」「早見表」「原因が見つからない場合」「補助テクニック」の順に並びます。最初に「症状への対処は失敗である」と言い切り、手順の文言を破ることは精神を破ることだ、と抜け道を塞ぐ書き方になっています。

使う場面

テスト失敗、本番のバグ、想定外の挙動、性能問題、ビルド失敗、連携の不具合など技術的な問題全般が対象です。特に、時間に追われているとき、すぐ直せそうに見えるとき、すでに何度か修正に失敗しているときこそ使うように、と書かれています。

4つの段階

第1段階：根本原因の調査。エラーメッセージとスタックトレースを最後まで読む、確実に再現できるようにする、最近の変更（差分、依存関係、設定）を確かめる、の3つに加え、複数のコンポーネントにまたがる仕組みでは、各境界で入出力や環境変数を記録する診断用の出力を入れて、一度実行してどこで壊れるかを確かめるよう指示します。CI のワークフローからビルドスクリプト、署名までを層ごとに確認するシェルの例が載っています。呼び出しの奥で起きるエラーは、悪い値がどこから来たかを遡って探します。

第2段階：パターン分析。同じコードベースで動いている似た例を探し、参照実装は飛ばし読みせず全部読み、動くものと壊れたものの違いを小さなものまで列挙します。

第3段階：仮説と検証。「X が原因だと考える、理由は Y」と一つの仮説を書き出し、一度に一つだけ最小の変更で確かめます。分からないときは分からないと言うことも求めています。

第4段階：実装。まず失敗するテストを作り（同じ Superpowers の test-driven-development スキルを使う）、原因に対する修正を一つだけ入れ、ついでの改善やリファクタリングは混ぜません。修正が効かなければ第1段階に戻り、3回失敗したら設計の問題として立ち止まり、人間と話し合うよう求めます。

危険信号と言い訳の表

「とりあえず直して後で調べる」「X を変えて様子を見る」「複数まとめて変えてテストする」といった考えが浮かんだら第1段階に戻れ、という一覧があります。人間から「それは本当に起きていないの？」「推測はやめて」と言われたら、やり方が間違っている合図だとも書かれています。さらに「急ぎだから手順は省く」などの言い訳と、それに対する反論を並べた表があります。

補助資料とスクリプト

• root-cause-tracing.md：呼び出しの奥で起きた不具合を、呼び出し元へ一段ずつ遡って最初のきっかけを見つける方法。空文字のディレクトリ指定が原因でテストが別の場所に git リポジトリを作ってしまう例を使い、スタックトレースを出力に仕込む方法も説明します。
• defense-in-depth.md：原因を直したあと、入口、業務ロジック、環境、デバッグ出力の4層で検証を入れ、同じバグが構造的に起きないようにする考え方。
• condition-based-waiting.md と condition-based-waiting-example.ts：固定時間の待機で不安定になっているテストを、目的の条件が満たされるまで待つ書き方に置き換える方法と TypeScript の実装例。
• find-polluter.sh：テストファイルを一つずつ実行し、指定したファイルやディレクトリを作ってしまうテストを特定する bash スクリプト。

出力の形

決まった書式のファイルは作りません。エージェントの作業の進め方を縛るスキルで、結果として、原因の説明、再現テスト、一点に絞った修正、検証の報告という順で作業が進むようになります。

README では、使っているエージェントごとにプラグインとして入れる方法が案内されています。Claude Code の場合は次のどちらかです。

# Anthropic 公式マーケットプレイスから
/plugin install superpowers@claude-plugins-official

# Superpowers のマーケットプレイスから
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Codex（アプリ・CLI）は公式プラグインマーケットプレイスから、Cursor は /add-plugin superpowers、Gemini CLI は gemini extensions install https://github.com/obra/superpowers、GitHub Copilot CLI は copilot plugin marketplace add obra/superpowers-marketplace のあと copilot plugin install superpowers@superpowers-marketplace、OpenCode は専用の INSTALL.md を読み込ませる方法が書かれています。ほかに Antigravity、Devin、Droid、Grok Build CLI、Kimi Code、Pi、Qwen Code の手順もあります。

このスキルだけを使いたい場合は、skills/systematic-debugging フォルダを ~/.claude/skills/ か .claude/skills/ に置く方法も Claude Code の仕組み上は可能です（README にはこの方法の記載はありません）。

• 単体でも使えるが、前提は Superpowers 全体：本文で test-driven-development や verification-before-completion といった同じスキル集の別スキルを呼ぶよう指示しています。このスキルだけを入れると、その部分は参照先がありません。
• プラグインは一式で入る：公式の入れ方はプラグインとしてのインストールで、ブレインストーミングや計画づくりなど他のスキルも一緒に入り、開発の進め方全体が変わります。
• 手順が厳格：小さな不具合でも段階を踏むよう求めるため、すぐ済ませたい場面ではやり取りが増えます。
• find-polluter.sh は bash 用で、テストの実行に npm test を呼ぶ前提で書かれています。
• ライセンスは MIT です。