Systematic Debugging

系统化调试

核心原则

总是先找到根因再尝试修复。 症状修复 = 失败。随机修复浪费时间并制造新 bug。

铁律

没有根因调查 = 没有修复

没完成阶段 1，不能提修复方案。

何时使用

任何技术问题：

• 测试失败
• 生产 Bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其在以下情况必须使用：

• 时间紧迫时（紧急情况最容易想猜）
• "就改一下"看起来很明显
• 已经试过多次修复
• 上次修复没起作用
• 你不完全理解这个问题

四阶段调试法

必须完成每个阶段再进入下个阶段。

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细读错误信息

• 不要跳过错误或警告
• 完整读堆栈跟踪
• 注意行号、文件路径、错误码

1. 稳定复现

• 能可靠触发吗？
• 精确步骤是什么？
• 每次都发生吗？
• 如果不能复现 → 收集更多数据，不要猜

1. 检查最近的变更

• 什么改变可能导致这个？
• git diff、最近的提交
• 新依赖、配置变更
• 环境差异

1. 多组件系统的证据收集

``` 在每个组件边界:

• 记录什么数据进入
• 记录什么数据出来
• 验证配置/环境传播

跑一次看哪里断了，然后再深入那层 ```

1. 追踪数据流

• 错误值的起源在哪里？
• 谁用错误值调用了这个？
• 向上追踪调用栈直到找到源头
• 在源头修复，不在症状处修复

阶段 2：模式分析

找到模式再修复：

1. 在代码库中找类似的工作示例
2. 完整对照参考——不要略读
3. 列出工作与失败之间的每个差异
4. 理解所有依赖和假设

阶段 3：假设+检验

1. 形成一个清晰的假设："我认为 X 是根因，因为 Y"
2. 明确写下来
3. 设计最小测试来证明/否定它
4. 跑测试
5. 如果被否定 → 形成新假设，重复
6. 如果被证明 → 进入修复

阶段 4：修复+验证

1. 在根因处修复，不在症状处
2. 写一个能捕获这个 bug 的测试
3. 验证修复有效
4. 验证无回归（全量测试套件）
5. 清晰提交信息，解释根因

反模式

• "试试这个" — 没有根因的随机修复
• "大概是 X" — 没有证据的猜测
• "快速补丁" — 症状修复，根因还在
• 一次改多个东西 — 无法知道哪个起效
• 跳过复现 — 调试一个不能稳定触发的问题

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yinqd3
• Source: yinqd3/workbuddy-skills
• License: MIT

Install and usage instructions live in the source repository linked above.