mcpField
S
systematic-debugging

systematic-debugging

github.com/itallstartedwithaidea開発4480 回インストール29 週間前に更新
リポジトリ

systematic-debugging について

コーディングエージェント向けのデバッグスキルです。バグの再現から、的を絞った予防策の実装と記録まで、4段階で根本原因を分析します。

主な機能

  1. 014段階の根本原因分析
  2. 02修正前のバグ再現
  3. 03仮説の順位付けと検証
  4. 04回帰テストと予防策の追加
  5. 05修正内容と事後分析の記録

活用シーン

  1. 01断続的なテスト失敗の調査
  2. 02スタックトレースからの問題特定
  3. 03本番と開発環境の挙動差の診断
  4. 04効果のなかった修正の再調査

インストール

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

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

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

詳細

系統的なデバッグ

googleadsagent.ai™ による Agent Skills™ の一部です。

説明

系統的なデバッグでは、試行錯誤による修正を、規律ある4段階の根本原因分析プロセスに置き換えます。エージェントはバグを確実に再現し、可能性の高い順に仮説を立て、最小限の計測で各仮説を検証し、的を絞った修正を多層防御で強化します。バグが存在する理由を理解する前に修正を適用することはありません。

エージェントは「手当たり次第のデバッグ」に陥りがちです。複数の箇所を同時に変更し、問題が消えることを期待するやり方です。このスキルでは、科学的な厳密さを徹底します。つまり、一度に変更する変数は1つとし、各段階で観測可能な証拠を確認し、根本原因から修正までの明確な因果関係を保ちます。エージェントは、修正コードを書く前に、根本原因を平易な言葉で説明しなければなりません。

直接的な修正の後、エージェントは多層防御を適用し、将来同じ種類のバグを検出できるアサーション、入力検証、監視を追加します。デバッグセッションの最後には、根本原因、修正内容、追加した予防策を記録した事後分析メモを作成します。

使用する場面

  • テストが予期せず、または断続的に失敗する場合
  • ユーザーからスタックトレースや再現手順とともにバグが報告された場合
  • コードの動作が開発環境と本番環境で異なる場合
  • エラーメッセージが不明瞭、または誤解を招く場合
  • 考えられる原因が複数あり、推測すると時間を浪費する場合
  • 以前の修正で問題が解決しなかった場合

仕組み

graph TD
    A[Bug Report] --> B[Phase 1: Reproduce]
    B --> C{Reproducible?}
    C -->|No| D[Gather More Context]
    D --> B
    C -->|Yes| E[Phase 2: Hypothesize]
    E --> F[Rank Hypotheses by Likelihood]
    F --> G[Phase 3: Test Top Hypothesis]
    G --> H{Root Cause Found?}
    H -->|No| I[Eliminate Hypothesis]
    I --> F
    H -->|Yes| J[Phase 4: Fix + Harden]
    J --> K[Write Regression Test]
    K --> L[Apply Defense-in-Depth]
    L --> M[Document Post-Mortem]

4つのフェーズによって厳格な順序が保たれます。再現できない問題は修正できず、理解していない問題は修正すべきではなく、再発を防がずにバグをクローズしてはなりません。

実装

class DebuggingSession:
    def __init__(self, bug_report):
        self.report = bug_report
        self.hypotheses = []
        self.evidence = []
        self.root_cause = None

    def phase_reproduce(self):
        """Create a minimal, reliable reproduction."""
        minimal_input = self.minimize_reproduction(self.report.steps)
        result = self.execute(minimal_input)
        assert result.matches(self.report.expected_failure), \
            "Cannot proceed without reliable reproduction"
        return ReproductionCase(minimal_input, result)

    def phase_hypothesize(self, repro):
        """Generate ranked hypotheses from evidence."""
        self.hypotheses = [
            Hypothesis("Race condition in async handler", likelihood=0.7),
            Hypothesis("Null reference from cache miss", likelihood=0.5),
            Hypothesis("Stale closure over mutable state", likelihood=0.3),
        ]
        return sorted(self.hypotheses, key=lambda h: -h.likelihood)

    def phase_test(self, hypothesis, repro):
        """Test one hypothesis with minimal instrumentation."""
        probe = self.instrument(hypothesis.target_area)
        result = self.execute_with_probe(repro, probe)
        if result.confirms(hypothesis):
            self.root_cause = hypothesis
        else:
            hypothesis.eliminated = True
            self.evidence.append(result)

    def phase_fix(self):
        """Apply targeted fix with defense-in-depth."""
        fix = self.root_cause.generate_fix()
        regression_test = self.root_cause.generate_regression_test()
        hardening = self.apply_defense_in_depth([
            InputValidation(self.root_cause.entry_point),
            AssertionGuard(self.root_cause.invariant),
            MonitoringAlert(self.root_cause.symptom),
        ])
        return DebugResult(fix, regression_test, hardening)
根本原因を追跡するためのチェックリスト
  1. メッセージだけでなく実際のエラーを読む — スタックトレース全体を確認します
  2. クラッシュした箇所ではなく、期待される動作から最初に逸脱した箇所を特定する
  3. git log --oneline -20 と git diff で最近の変更を確認する
  4. 入力データ、環境の状態、依存関係に関する前提を検証する
  5. 推測せずに計測する — 逸脱した箇所にログを追加します

ベストプラクティス

  • 仮説を立てる前に必ず再現します。フェーズ1を省略してはいけません
  • 有効な仮説は、可能性と検証可能性の高い順に3〜5個までにします
  • 因果関係を明確に保つため、各テストサイクルで変更する変数は1つにします
  • 修正を適用する前に回帰テストを書きます
  • 多層防御を適用します。修正に加え、検証、アサーション、監視を追加します
  • 「明白な」バグでも根本原因を記録します。時間とともにパターンが明らかになります

プラットフォームの互換性

プラットフォーム対応状況備考
Cursor完全対応再現にはデバッガーと Shell を使用
VS Code完全対応統合デバッガーに対応
Windsurf完全対応ターミナルベースのデバッグ
Claude Code完全対応計測用の Shell アクセス
Cline完全対応ステップ実行によるデバッグ
aider部分対応ログベースのデバッグに限定

関連スキル

キーワード

debugging root-cause-analysis systematic-debugging reproduce-hypothesize-test-fix defense-in-depth regression-test post-mortem bug-fix

© 2026 googleadsagent.ai™ | Agent Skills™ | MIT License

コメント

Markdown 対応