systematic-debugging

系统化调试

适用场景

• 需要调查 Bug、错误、异常或崩溃
• 某些功能“无法正常工作”，但原因不明
• 测试失败，且原因不明显
• 需要排查任何语言或框架中的意外行为

核心工作流

按顺序完成以下五个阶段。完成隔离和追踪之前，不要跳到修复阶段。

阶段 1：复现

在进行其他操作之前，先建立一种可靠的方式来触发 Bug。

1. 阅读完整的错误消息、堆栈跟踪和日志——记下准确文本、行号和错误代码
2. 创建一个能够稳定触发问题的最小复现用例
3. 记录导致故障的确切步骤、输入和环境

**检查点：**你能按需触发 Bug 吗？如果问题是间歇性的，请先收集更多数据再继续。

阶段 2：隔离

缩小故障来源的范围。

1. 使用二分法找出故障组件——禁用或替换系统的一半组件
2. 使用 git log --oneline -20 和 git diff 对比上一个已知正常的状态，检查近期更改
3. 添加有针对性的日志，或使用调试器观察关键边界处的状态

# Find which commit introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Git will checkout midpoints — test each one and mark good/bad

**检查点：**已将 Bug 追踪到特定函数、模块或数据流。

阶段 3：追踪到根本原因

弄清楚故障为何发生，而不只是发生在哪里。

1. 完整阅读从入口点到故障位置的代码路径
2. 检查假设：每个函数预期接收什么，实际又接收了什么？
3. 反向追踪数据流——错误值从哪里产生？
4. 用证据验证：添加断言或打印语句，以确认你的假设

# Example: verify assumptions about incoming data
def process_order(order):
    assert order.status == "pending", f"Expected pending, got {order.status}"
    assert order.items, "Order has no items"
    # ... rest of processing

**检查点：**已解释从触发条件到症状的因果链，并有支持证据（日志、断言、调试器输出）。

阶段 4：从根本原因着手修复

实施有针对性的修复，解决实际原因，而不只是症状。

1. 修复根本原因，而非下游影响
2. 保持修复精简——只更改必要内容
3. 避免用“临时补丁”掩盖底层问题（例如，崩溃时添加 try/except，却不解决崩溃原因）

阶段 5：验证

确认修复有效，且没有引入回归问题。

1. 运行阶段 1 中的复现用例——确认 Bug 已消失
2. 运行完整测试套件，检查是否存在回归问题
3. 测试与修复相关的边缘情况
4. 如果 Bug 是因为缺少测试而未被发现，请添加一个本可捕获该 Bug 的测试

**检查点：**复现用例通过，测试套件全部通过，并且新增了一个覆盖此 Bug 的测试。

应避免的主要反模式

• 盲目调试：随机修改，只希望某种改动能奏效
• 修复后祈祷：不了解原因就应用修复
• 跳过复现：未确认能触发 Bug 就直接修改代码
• 只修症状：用 try/catch 包装错误，而不修复产生错误的原因

完整目录请参阅 anti-patterns.md。

相关技能

• root-cause-tracing：深入追踪调用栈的技巧——阶段 2 之后，如果 Bug 位于较深的执行链中，可使用此技能
• verification-before-completion：强制验证关卡——在宣称修复完成前，加强阶段 5 的验证

深入参考

• workflow.md：包含决策树的逐阶段详细说明
• examples.md：跨语言的调试实例
• troubleshooting.md：常见调试场景及解决方案
• anti-patterns.md：应避免的模式及识别方法