superpowers-zh
← Back to all skills

Systematic Debugging

systematic-debugging

Reproduce and locate the root cause before proposing any fix.

$ npx superpowers-zh
View source on GitHub ↗
📖 This skill's content is written in Chinese — superpowers-zh is a Chinese-localized toolkit.

系统化调试

概述

随意修复既浪费时间又会引入新 bug。草率的补丁只会掩盖深层问题。

核心原则： 在尝试修复之前，务必先找到根本原因。只修症状就是失败。

敷衍走流程等于违背调试的精神。

铁律

不做根因调查，不许提修复方案

如果你还没完成第一阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

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

以下情况也不要跳过：

四个阶段

你必须完成每个阶段后才能进入下一个。

第一阶段：根因调查

在尝试任何修复之前：

  1. 仔细阅读错误信息
    • 不要跳过错误或警告
    • 它们往往直接包含解决方案
    • 完整阅读堆栈跟踪
    • 记下行号、文件路径、错误码
  1. 稳定复现
    • 你能可靠地触发它吗？
    • 具体的复现步骤是什么？
    • 每次都能复现吗？
    • 如果无法复现 → 收集更多数据，不要猜测
  1. 检查近期变更
    • 什么变更可能导致了这个问题？
    • git diff、最近的提交
    • 新依赖、配置变更
    • 环境差异
  1. 在多组件系统中收集证据

当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

在提出修复方案之前，先添加诊断埋点： ``` 对每个组件边界：

执行一次以收集证据，确定断裂点在哪里 然后分析证据，定位故障组件 然后针对该组件深入调查 ```

示例（多层系统）： ```bash # 第 1 层：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 第 2 层：构建脚本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment"

# 第 3 层：签名脚本 echo "=== Keychain state: ===" security list-keychains security find-identity -v

# 第 4 层：实际签名 codesign --sign "$IDENTITY" --verbose=4 "$APP" ```

由此可以看出： 哪一层出了问题（secrets → workflow ✓, workflow → build ✗）

  1. 跟踪数据流

当错误发生在调用栈深处时：

参见本目录下的 root-cause-tracing.md，了解完整的反向追踪技术。

简要版本：

第二阶段：模式分析

先找到模式，再修复：

  1. 找到可正常工作的示例
    • 在同一代码库中找到类似的正常代码
    • 有什么正常的代码与出问题的代码相似？
  1. 与参考实现对比
    • 如果是实现某个模式，完整阅读参考实现
    • 不要略读——逐行阅读
    • 在应用之前彻底理解该模式
  1. 识别差异
    • 正常代码和出问题的代码之间有什么不同？
    • 列出每一个差异，无论多小
    • 不要假设"那不可能有影响"
  1. 理解依赖关系
    • 这个功能需要哪些其他组件？
    • 需要哪些设置、配置、环境？
    • 它有哪些隐含假设？

第三阶段：假设与验证

科学方法：

  1. 提出单一假设
    • 清晰地陈述："我认为 X 是根本原因，因为 Y"
    • 写下来
    • 要具体，不要含糊
  1. 最小化测试
    • 做出最小的改动来验证假设
    • 每次只改一个变量
    • 不要同时修复多个问题
  1. 继续之前先验证
    • 生效了？是 → 进入第四阶段
    • 没生效？提出新假设
    • 不要在上面叠加更多修复
  1. 当你不确定时
    • 说"我不理解 X"
    • 不要假装自己知道
    • 寻求帮助
    • 做更多调研

第四阶段：实施

修复根本原因，而非症状：

  1. 创建失败的测试用例
    • 最简化的复现
    • 尽可能用自动化测试
    • 没有测试框架就写一次性测试脚本
    • 修复前必须先有测试
    • 使用 superpowers:test-driven-development 技能来编写规范的失败测试
  1. 实施单一修复
    • 修复已定位的根本原因
    • 每次只改一处
    • 不做"顺便改改"的优化
    • 不捆绑重构
  1. 验证修复
    • 测试现在通过了吗？
    • 其他测试没有被破坏吧？
    • 问题真的解决了吗？
  1. 如果修复不起作用
    • 停下来
    • 数一数：你已经尝试了几次修复？
    • 少于 3 次：回到第一阶段，用新信息重新分析
    • 3 次或以上：停下来质疑架构（见下方第 5 步）
    • 没有经过架构讨论，不要尝试第 4 次修复
  1. 如果 3 次以上修复都失败了：质疑架构

以下模式表明存在架构问题：

停下来质疑根本性问题：

在尝试更多修复之前，和你的搭档讨论

这不是假设失败——这是架构有误。

红线——停下来，按流程走

如果你发现自己在想：

以上这些都意味着：停下来。回到第一阶段。

如果 3 次以上修复都失败了： 质疑架构（见第四阶段第 5 步）

搭档发出的信号——说明你的方法不对

留意这些提醒：

当你看到这些信号时： 停下来。回到第一阶段。

常见借口

借口现实
"问题很简单，不需要走流程"简单问题也有根本原因。对于简单 bug，流程很快就能走完。
"紧急情况，没时间走流程"系统化调试比反复猜测式修复更快。
"先试一下，再排查"第一次修复就定下了基调。从一开始就做对。
"确认修复有效后再写测试"没有测试的修复留不住。先写测试才能证明修复有效。
"一次修多个问题省时间"无法隔离哪个生效了。还会引入新 bug。
"参考实现太长了，我自己改改"一知半解必然出 bug。完整阅读。
"我看出问题了，让我修一下"看到症状 ≠ 理解根因。
"再试一次"（在 2 次以上失败后）3 次以上失败 = 架构问题。质疑模式，不要继续修。

速查表

阶段关键活动通过标准
1. 根因阅读错误、复现、检查变更、收集证据理解了什么出了问题以及为什么
2. 模式找到正常示例、对比识别出差异
3. 假设提出理论、最小化验证假设被验证或产生新假设
4. 实施创建测试、修复、验证bug 已修复，测试通过

当流程显示"找不到根因"

如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的：

  1. 你已经完成了流程
  2. 记录你排查了什么
  3. 实施适当的处理措施（重试、超时、错误提示）
  4. 添加监控/日志以便后续排查

但是： 95% 的"找不到根因"其实是排查不充分。

辅助技术

以下技术是系统化调试的组成部分，可在本目录中找到：

相关技能：

实际效果

调试实践中的数据：

← Back to all skills