mcpField
S
systematic-debugging

systematic-debugging

github.com/izyanrajwani開発483 回インストール2 週間前に更新
リポジトリ

systematic-debugging について

根本原因を特定してからコードを変更することを重視する、開発者やコーディングエージェント向けのデバッグスキルです。証拠収集、仮説の個別検証、修正失敗が続く場合のエスカレーションを段階的に示します。

主な機能

  1. 01エラーの確認と問題の再現
  2. 02最近の変更とデータフローの調査
  3. 03コンポーネント間の証拠収集
  4. 04仮説を一つずつ検証
  5. 05修正失敗が続く場合のエスカレーション

活用シーン

  1. 01再現可能な不具合の調査
  2. 02システム境界をまたぐ障害の追跡
  3. 03修正失敗後の方針再検討

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/izyanrajwani/agent-skills-library --skill systematic-debugging

インストール後、Claude Code で/systematic-debuggingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
condition-based-waiting.md
defense-in-depth.md
root-cause-tracing.md
scripts/
condition-based-waiting-example.ts
find-polluter.sh

詳細

系統的なデバッグ

基本原則： 修正を試みる前に、根本原因を特定してください。症状だけを修正するのは失敗です。

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

修正を試みる前に、必ず次のことを行ってください。

  1. エラーメッセージを注意深く読む

    • スタックトレースを最後まで読む
    • 行番号、ファイルパス、エラーコードを確認する
    • 警告を読み飛ばさない

  2. 一貫して再現する

    • 正確な手順は何か？
    • 再現できない場合 → 推測せず、さらにデータを集める

  3. 最近の変更を確認する

    • Git の差分、最近のコミット
    • 新しい依存関係、設定の変更
    • 環境の違い

  4. 複数コンポーネントから成るシステムで証拠を集める

    システムに複数のコンポーネントがある場合（CI → ビルド → 署名、API → サービス → データベース）：

    修正案を出す前に、診断用の計測機能を追加します。

    For EACH component boundary:
  - Log what data enters/exits component
  - Verify environment/config propagation
  - Check state at each layer

Run once to gather evidence → analyze → identify failing component

    例：

    # Layer 1: Workflow
echo "=== Secrets available: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# Layer 2: Build script
env | grep IDENTITY || echo "IDENTITY not in environment"

# Layer 3: Signing
security find-identity -v

  5. データフローを追跡する

    逆方向に追跡する手法については、references/root-cause-tracing.md を参照してください。

    簡単に言うと、誤った値はどこから来ているのか？ 呼び出しチェーンをさかのぼり、発生源を見つけます。発生源を修正してください。

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

  1. 動作する例を見つける - コードベース内の、同様に動作するコード
  2. 参照例と比較する - 参照実装を最後まで読み、流し読みしない
  3. 違いを特定する - 「関係ないはず」と決めつけず、すべての違いを列挙する
  4. 依存関係を理解する - コンポーネント、設定、環境、前提条件

フェーズ 3：仮説と検証

  1. 仮説を 1 つ立てる - 「Y が理由で、X が根本原因だと思います」- 具体的に述べる
  2. 最小限のテストを行う - 可能な限り小さな変更を行い、一度に変える変数は 1 つだけにする
  3. 検証する - うまくいった場合 → フェーズ 4 へ。うまくいかなかった場合 → 修正を積み重ねず、新しい仮説を立てる
  4. 分からないときは - そう伝える。分かったふりをしない

フェーズ 4：実装

  1. 失敗するテストケースを作成する

    • test-driven-development スキルを使用する
    • 修正前に必ず作成する

  2. 修正を 1 つ実装する

    • 一度に変更するのは 1 つだけ
    • 「ついでに」改善しない

  3. 修正を検証する

    • テストは通るか？ ほかのテストも引き続き通るか？ 問題は解決したか？

  4. 修正がうまくいかなかった場合

    • 試した回数を数える
    • 3 回未満の場合：新しい情報をもとにフェーズ 1 に戻る
    • 3 回以上の場合：エスカレーションする（以下を参照）

エスカレーション：3 回以上修正に失敗した場合

アーキテクチャ上の問題を示すパターン：

  • 修正のたびに、別の場所で新たな問題が見つかる
  • 修正に大規模なリファクタリングが必要になる
  • 共有状態や結合の問題が何度も表面化する

対応： いったん止めて、根本を問い直してください。

  • このパターンは根本的に妥当か？
  • 慣性で続けていないか？
  • 症状の修正を続けるのではなく、アーキテクチャをリファクタリングすべきではないか？

修正をさらに試みる前に、人間のパートナーと話し合ってください。 これは仮説の誤りではなく、アーキテクチャの誤りです。

危険信号 → 作業を止めてフェーズ 1 に戻る

次のように考えていることに気づいたら：

  • 「とりあえず手早く直して、調査はあとで」
  • 「X を変えてみよう」
  • 「テストは飛ばそう」
  • 「たぶん X だ」
  • 「パターンでは X だけど、違う形に応用しよう」
  • データフローを追跡する前に解決策を提案している
  • 2 回以上失敗したあとに「もう 1 回だけ修正しよう」と考えている

軌道を外れていることを示す人間からのサイン

  • 「それは起きていないのでは？」 → 検証せずに決めつけていた
  • 「それで分かるのは……では？」 → 証拠を集めるべきだった
  • 「推測はやめて」 → 理解しないまま修正案を出している
  • 「徹底的に考えて」 → 根本を問い直す
  • いら立った様子で「行き詰まっているの？」 → そのアプローチはうまくいっていない

対応： フェーズ 1 に戻ってください。

補足テクニック

references/ 内の参照ファイル：

  • root-cause-tracing.md - 呼び出しスタックをさかのぼってバグを追跡する
  • defense-in-depth.md - 根本原因の特定後、複数のレイヤーに検証を追加する
  • condition-based-waiting.md - 任意のタイムアウトを条件のポーリングに置き換える

関連スキル：

  • test-driven-development - 失敗するテストケースを作成する（フェーズ 4）
  • verification-before-completion - 成功を報告する前に修正を検証する

コメント

Markdown 対応