systematic-debugging

系统化调试

属于 Agent Skills™，由 googleadsagent.ai™ 提供

描述

系统化调试以严谨的四阶段根因分析流程取代试错式修复。Agent 会可靠地重现错误，生成按优先级排序的假设，用最少的检测手段逐一验证，并通过纵深防御加固来实施有针对性的修复。在理解错误为何存在之前，不会应用任何修复。

Agent 容易采用“撒网式调试”——同时更改多项内容，并寄希望于问题就此消失。这项技能要求遵循科学严谨性：一次只改变一个变量，在每个步骤中获取可观察的证据，并建立从根因到修复的清晰因果链。编写任何纠正性代码之前，Agent 必须用通俗语言说明根因。

完成直接修复后，Agent 会实施纵深防御：添加断言、输入验证或监控，以便将来能够捕获同类错误。调试结束时，还会撰写事后总结，记录根因、修复方案和新增的预防措施。

适用场景

• 测试意外失败或间歇性失败
• 用户报告错误，并提供堆栈跟踪或复现步骤
• 代码在生产环境中的行为与开发环境不同
• 错误消息含糊不清或具有误导性
• 存在多种可能的原因，猜测会浪费时间
• 之前尝试的修复未能解决问题

工作原理

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]

这四个阶段要求严格按顺序推进：无法复现的问题就无法修复，不了解的问题不应修复，并且必须防止错误再次发生后才能关闭问题。

实施

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 个，并按可能性和可测试性排序
• 每轮测试只更改一个变量，以保持因果关系清晰
• 应用修复前先编写回归测试
• 实施纵深防御：除修复本身外，还要添加验证、断言和监控
• 即使错误“显而易见”，也要记录根因——随着时间推移，规律会逐渐显现

平台兼容性

平台	支持情况	备注
Cursor	完全支持	使用调试器和 Shell 进行复现
VS Code	完全支持	支持集成调试器
Windsurf	完全支持	基于终端进行调试
Claude Code	完全支持	可通过 Shell 进行检测
Cline	完全支持	支持单步调试
aider	部分支持	仅支持基于日志的调试

相关技能

• 测试驱动开发 - 修复前先编写能暴露错误的失败测试
• 代码审查 - 合并前审查修复和回归测试的质量
• Agent 安全扫描 - 面向安全的分析，可在调试期间找出漏洞根因

关键词

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