systematic-debuggingでバグの根本原因を突き止める

使うとこうなる

systematic-debuggingを入れると、エージェントは原因を確かめるまで修正案を出さなくなります。たとえば、次のように頼んだとします。

このテスト失敗を再現し、最近の変更とログから原因を調べてください

エージェントはまずエラーメッセージとスタックトレースを最後まで読み、行番号やファイルパス、エラーコードを書き留めます。次にテストを実行し、毎回再現するかを確かめる流れです。

続いて、git diffや直近のコミット、依存関係や設定の変更を見ていきます。再現しない場合も推測では直さず、追加のデータを集める段取りになっています。

原因の候補が見えたら、同じコードベースで正常に動く似たコードと比べ、小さな違いまで一つずつ挙げます。そのうえで書き出す仮説は、「原因はXで、理由はY」という形の1つだけ。これを最小の変更で確かめます。仮説が外れても修正は上乗せせず、新しい仮説を立て直す流れです。

仮説が当たっても、すぐにはコードを直しません。先に不具合を再現する失敗テストを作り、根本原因に対する修正を1つだけ入れます。最後に、そのテストが通るか、他のテストが失敗していないかを確かめてから結果が返ってきます。

systematic-debuggingでできること

systematic-debuggingは、デバッグを4つの段階に分け、前の段階を終えるまで次へ進ませないスキルです。中心にあるのは「根本原因を調べる前に修正しない」という原則で、症状だけを消す修正は失敗とみなします。各段階の中身は次のとおりです。

段階	エージェントがすること	次へ進む条件
1. 根本原因の調査	エラーを読む、再現する、直近の変更を確認する、証拠を集める	何が起きていて、なぜ起きるかが分かる
2. パターン分析	正常に動く例や参照実装を探して比べる	不具合のあるコードとの違いが特定できる
3. 仮説と検証	仮説を1つ立て、最小の変更で試す	仮説が確かめられる（外れたら新しい仮説へ）
4. 実装	失敗テストを作り、修正を1つ入れ、確認する	不具合が解消し、テストが通る

複数の処理をまたぐ不具合を絞り込む

複数の処理をまたぐ不具合では、修正の前に診断用のログを入れます。CIからビルド、署名へと進む流れや、APIからサービス、データベースへとつながる処理が対象です。

各処理の境目では、入ってくるデータと出ていくデータ、環境変数や設定の受け渡しを記録します。そのうえで一度実行し、どこで問題が起きるかを確かめます。問題のある層が分かってから、その層だけを詳しく調べる手順です。

呼び出しの深い場所でエラーが出た場合は、不正な値がどこから来たかを呼び出し元へさかのぼって探します。修正を入れるのは、症状が出た場所ではなく値が生まれた場所というのが原則です。

この逆向きの追跡手順には解説が付いています。原因が分かった後に複数の層で入力を検証する方法や、固定の待ち時間を条件の確認に置き換える方法も、同じく解説の対象です。

繰り返し失敗する修正を止める

エージェントは修正を試すたびに回数を数え、3回以上失敗したら4回目の修正には進みません。直すたびに別の場所で新しい問題が出る状態や、修正に大規模な作り直しが必要になる状態は、設計そのものの問題として扱います。このときエージェントは追加の修正をやめ、設計を見直すかどうかを利用者と相談します。

調べ尽くした結果、環境やタイミング、外部要因が原因だと分かることもあるでしょう。その場合は調べた内容を記録し、リトライやタイムアウト、エラーメッセージで対処します。あわせて、次の調査に備えて監視やログを追加します。

systematic-debuggingは、GitHubのobra/superpowersに含まれるスキルの1つです。リポジトリのスター数は309,845。同じリポジトリには、ブレインストーミングやコードレビューなど開発の流れに沿ったスキルが並んでいます。

インストール方法

ターミナルで次のコマンドを実行すれば、obra/superpowersからsystematic-debuggingだけを追加できます。入れる先のエージェントは、Claude CodeやCodexなどから実行時に選ぶ形です。

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

エージェントに任せる場合は、次の文面をそのまま送ってください。中身の確認を先に頼む書き方なので、エージェントは不審な処理がないかを確かめてから配置まで進みます。

次の Agent Skill をインストールしてください。
https://github.com/obra/superpowers/tree/main/skills/systematic-debugging

まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/systematic-debugging/、Codex なら ~/.agents/skills/systematic-debugging/ に配置してください。

置き場所は、使うエージェントと適用範囲で決まります。

エージェント	すべてのプロジェクトで使う	特定のプロジェクトだけで使う
Claude Code	~/.claude/skills/systematic-debugging/	プロジェクトの.claude/skills/systematic-debugging/
Codex	~/.agents/skills/systematic-debugging/	プロジェクトの.agents/skills/systematic-debugging/

入ったかどうかの目安は、フォルダの中にSKILL.mdがあるかどうかです。Claude Codeに全体用として入れた場合は、次のコマンドで中身を表示できます。

ls ~/.claude/skills/systematic-debugging/

SKILL.mdのほか、解説用のMarkdownファイル、TypeScriptの例、シェルスクリプトが並んでいれば配置は完了です。

使い方の例

このスキルは、修正を提案する前に使う前提で作られています。バグやテスト失敗、予期しない動作に出会ったときが使いどころです。依頼文に症状と調べてほしい範囲を書くと、調査の出発点がはっきりします。

昨日からログイン処理のテストが失敗しています。修正する前に、再現手順と直近のコミットを確認して原因を特定してください

返ってくるのは、再現できたかどうか、関係しそうなコミットや設定の変更、根拠付きの仮説です。仮説が確かめられた後に、失敗テストと1つの修正が続きます。

APIからデータベースまでの処理を追い、どこで不正な値が入るか確認してください

本番の不具合を追う依頼です。エージェントは各層の境目に診断用のログを入れて一度実行し、どの層で値がおかしくなったかを示します。修正は、不正な値が生まれた場所に対して提案されます。

CIのビルドで署名に失敗します。ワークフロー、ビルドスクリプト、署名の各段階で何が渡っているかを確認してください

ビルドや連携の失敗では、段階ごとの確認を入れて切り分けます。シークレットは値そのものではなく「設定あり／なし」で表示し、キーチェーンの状態も確かめます。こうして「ワークフローまでは届くが、ビルドスクリプトには渡っていない」のように、問題のある段階を特定する流れです。

注意点

調査がどこまで進むかは、最初に渡す材料で変わります。このスキルは、再現できない不具合を推測では直さず、データ集めに戻る手順です。再現手順やエラーメッセージの全文、ログ、起き始めた時期を最初に渡すほど、調査は早く原因に近づきます。

修正内容の最終確認は人が行います。診断用に追加したログや確認処理が、修正のコミットに残っていないかも見ておくと安心です。

修正が3回以上失敗した場面では、エージェントの側から設計の相談が来ます。続けるか作り直すかを判断するのは利用者です。

失敗テストの書き方と完了前の確認は、同じsuperpowersの別スキル（テスト駆動開発と完了前の検証）を参照する手順になっています。systematic-debuggingだけを入れた場合、その2つの指示は手元にありません。必要に応じて、リポジトリからの追加を検討してください。

ライセンスはMITです。SKILL.mdは英語で書かれており、付属ファイルにはシェルスクリプトとTypeScriptの例も含まれます。入れる前に、SKILL.mdと付属ファイルの中身を一度読んでおいてください。

関連スキル

同じobra/superpowersには、デバッグの前後で使えるスキルがあります。

dispatching-parallel-agentsは、互いに依存しない不具合やテスト失敗を別々のエージェントに割り当て、並行して調査・修正するスキルです。失敗が複数の場所で同時に出ているときは、systematic-debuggingの調査を分担させる使い方ができます。

requesting-code-reviewは、実装後やマージ前に別のエージェントへコードレビューを依頼するスキルです。根本原因を直した後、変更内容を第三者の目で確かめたいときに向いています。

finishing-a-development-branchは、全テストを確認したうえで、マージやPull Request作成を選んで進めるスキルです。修正を終えたブランチの片付けまで、続けて任せられます。

まとめ

systematic-debuggingは、エージェントに「根本原因を調べるまで修正しない」という順序を守らせるスキルです。エラーの読み込み、再現、変更履歴の確認から仮説の検証、失敗テストによる修正の確認までを1段階ずつ進めます。

3回失敗したら設計の相談に切り替わるため、場当たり的な修正の繰り返しを止められます。AIに頼んだ修正が同じ失敗を繰り返しているなら、まずこのスキルを入れて調査から任せてみてください。

cccskillsのページ