systematic-debugging

不具合・テストの失敗・想定外の挙動に出会ったとき。修正を提案する前です。

中核の原則が 1 行で書かれています。

常に、修正の前に根本原因を見つけよ。症状への修正は失敗である。

そして「この工程の文言に違反することは、デバッグの精神に違反する」。手順を守ることそのものが要求されています。

鉄の法則

本文にコードブロックで囲まれた 1 行があります。

根本原因の調査なしに修正は無い

続けて「第 1 段階を終えていないなら、修正を提案することはできない」。

修正の提案を段階で封じるのがこのスキルの骨格です。

急いでいるときこそ使え、と書いてある

使う場面の列挙が的確です。「特にこういうときに使え」として、5 つの状況が並んでいます。2 列目は、1 行目が本文の理由、残りは当サイトの補足です。

• 時間に追われている緊急事態は当て推量を誘う
• 「1 つ直せば済む」が明らかに見える明らかに見えるものが当たるとは限らない
• すでに複数の修正を試した試した数が多いほど原因から遠い
• 前の修正が効かなかった同じ場所を触り続ける
• 問題を完全に理解していない理解する前の修正は当て推量

飛ばしてよくない場面

飛ばしてよくない場面も別に書かれています。「単純に見える（単純な不具合にも根本原因はある）」「急いでいる（急ぐと手戻りが確定する）」「上司がいますぐ直せと言っている（順序立てたほうが、あがくより速い）」。

4 つの段階。前の段階を終えるまで次へ進めない

1. 根本原因の調査エラーを読み、再現し、直近の差分を見て、境界に計測を足し、データの流れを遡る
2. 型の分析似ていて動くものと比べる
3. 仮説と検証仮説を 1 つに絞って試す
4. 実装直す前に、失敗するテストを持つ

第 1 段階でやることが 5 つある

1. エラーの文言を丁寧に読む。飛ばさない。スタックトレースを最後まで。行番号・ファイル経路・エラーコードを控える
2. 確実に再現する。毎回起きるか。再現できないならデータを集める。推測しない
3. 直近の変更を確認する。差分、コミット、新しい依存、設定、環境の違い
4. 複数の部品をまたぐ系では、先に計測を足す（後述）
5. データの流れを遡る。悪い値はどこで生まれたか。源で直す。症状で直さない

★境界にログを足させるのが鋭い

4 番目が、この手のスキルとしては踏み込んでいます。

系が複数の部品を持つとき（CI → ビルド → 署名、API → サービス → DB）、修正を提案する前に、診断のための計測を足せ。

部品の境界ごとに——入ってくるデータを記録し、出ていくデータを記録し、環境や設定が伝わっているかを確かめ、各層の状態を見る。

1 回走らせて、どこで壊れているかの証拠を集める。そのあとで壊れている部品を特定し、そこを調べる。

本文には 4 層の具体例（ワークフロー → ビルドの手順 → 署名の手順 → 実際の署名）まで載っていて、どの層で落ちたかが分かる形になっています。

「どこが悪いか分からないまま直し始める」を止める仕掛けです。

第 3 段階は仮説を 1 つに絞らせる

★第 4 段階に「3 回で立ち止まる」規則がある

ここが最も価値のある部分です。

修正が効かなかったら——止まれ。いくつ試したか数えよ。

• 3 回未満なら第 1 段階へ戻り、新しい情報で分析し直す
• 3 回以上なら止まって、設計を疑え
• 4 回目の修正を、設計の議論なしに試みるな

設計の問題を示す型まで挙げられています。

• 修正のたびに、別の場所に新しい共有状態や結合が現れる
• 修正に「大規模な書き直し」が必要になる
• 修正のたびに、別の場所に新しい症状が出る

そして問い直す言葉が 3 つ。「この型は根本的に健全か」「惰性だけで続けていないか」「症状を直し続けるより、設計を書き直すべきではないか」。

修正の回数を数えさせるスキルは珍しいです。同じ場所を 4 回叩いている状態を、機械的に検出できる形にしています。

「根本原因が無い」と言う前に

調べ尽くして、本当に環境・タイミング・外部の要因だったときの扱いも書かれています。調べたことを記録し、再試行・時間切れ・エラー表示などの扱いを入れ、次に備えて監視やログを足す、という手順です。

ただし「根本原因が無い」の 95% は調査不足だ、と釘を刺しています。

他のスキルを呼ぶ位置が決まっている

第 4 段階に「直す前に、失敗するテストを必ず持て」とあります。

次の 5 つの場面では、重すぎるか、手が届きません。

• 仕様が明確な小さい変更文言の差し替えに 4 段階を通す意味は無い
• 再現できない環境第 1 段階の 2 番目が再現なので止まる
• 新機能の設計brainstorming の側
• 「1 コマンドで赤くする」から入りたいdiagnosing-bugs は再現を 1 コマンドに固めるところから始める
• 人が応答できない状況3 回失敗したら設計の議論に入る

仕様が明確な小さい変更

仕様が明確な小さい変更には重すぎます。文言の差し替えに 4 段階を通す意味はありません。

再現できない環境

再現できない環境には手が届きません。第 1 段階の 2 番目が再現なので、環境にアクセスできないと止まります。その場合はデータを集める側に回ります。

新機能の設計

新機能の設計には使えません。そちらは brainstorming の側です。

「1 コマンドで赤くする」から入りたいとき

「1 コマンドで赤くする」から入りたいなら別物です。diagnosing-bugs は再現を 1 コマンドに固めるところから始めます。目的は近いですが、入り方が違います。

人が応答できない状況

人が応答できない状況では止まります。 3 回失敗したら設計の議論に入る設計です。

シェルコマンドを実行する記述がある

SKILL.md の解析では、シェルコマンドを実行する記述が見つかっています。同梱ファイルは 10 件で、root-cause-tracing.md のような技法の資料が分かれています（2026-10-09 確認）。

コードに一時的な出力を書き込む

コードとログを読み、テストやコマンドを実行します。計測を足す段ではコードに一時的な出力を書き込みます。消し忘れに注意してください（スキルを入れる前に確認すること）。

ログに秘密の値が出ることがある

本番の系に計測を足す場合

本番の系に計測を足す場合は影響を確かめてください。ログの量が増えると、費用と性能に効きます。

時間はかかる

時間はかかります。4 段階を通すので、当て推量より遅く感じます。本文は「順序立てたほうが、あがくより速い」と主張していますが、1 回目の修正で当たる場合はこのほうが遅いのは事実です。

ライセンス

ライセンス: MIT。再配布や商用利用の前に公開元の表記を確認してください。

すぐ直してもらえませんか

設計上、できません。鉄の法則が「根本原因の調査なしに修正は無い」で、第 1 段階を終えていないと修正を提案できない、と明記されています。

急ぐなら、依頼文で「第 1 段階の結果だけ先に見せて」と区切ってください。

複数の層をまたぐ不具合はどう調べますか

境界ごとにログを足してから、1 回走らせます。修正を提案する前に、どこで壊れているかの証拠を集める手順です。

本文には 4 層の具体例が載っています。「秘密の値はワークフローに届いているが、ビルドに渡っていない」のような形で切り分けます。

何度直しても戻るときは

3 回で立ち止まります。本文が回数を数えさせます。3 回以上失敗したら、4 回目を試す前に設計を疑う指示です。

判断の材料も挙げられています。修正のたびに別の場所に症状が出るなら、設計の問題です。

仮説を複数試してもらえませんか

1 つずつです。一度に 1 変数、最小の変更で試す規則です。

複数同時に変えると、どれが効いたか分からなくなります。

diagnosing-bugs とどちらを使いますか

入り方が違います。

両方入れると調査の指示が二重になるので、どちらかに寄せてください。

対応しているエージェントはどれですか

Claude Code と Codex です。公開元は群の入口（using-superpowers）に実行環境ごとの補足ファイルを置き、writing-skills では Claude Code・Codex・Copilot CLI・Gemini CLI の置き場所まで書き分けています。

当サイトは公開元が明記しているものだけを表示しています（指標の意味と限界）。