用途
Systematic Debugging 是一个系统化调试框架技能,用于在遇到任何技术问题时,在提出修复方案之前进行结构化排查。它适用于测试失败、生产环境 bug、异常行为、性能问题、构建失败、集成问题等各类技术问题。技能特别强调在时间压力大、看似有「快速修复」、已尝试多次修复、上一次修复无效、或尚未完全理解问题时使用。
核心原则
技能的核心原则是:始终在尝试修复之前找到根本原因,只修复症状属于失败。技能提出「铁律」:未先进行根本原因调查,不得提出修复方案。如果未完成第一阶段,就不能提出修复方案。
四个阶段
技能要求必须完成每个阶段后才能进入下一阶段。
第一阶段:根本原因调查。 在尝试任何修复之前:仔细阅读错误信息(不要跳过错误或警告,完整阅读堆栈跟踪,记录行号、文件路径、错误代码);稳定复现问题(能否可靠触发、确切步骤是什么、是否每次都发生,若无法复现则收集更多数据而非猜测);检查近期变更(git diff、近期提交、新依赖、配置变更、环境差异);在多组件系统中收集证据(当系统有多个组件如 CI → build → signing、API → service → database 时,在提出修复前添加诊断插桩,对每个组件边界记录进入和退出的数据、验证环境/配置传播、检查各层状态,运行一次以收集证据显示在哪里中断,然后分析证据识别失败组件,再调查该特定组件);追踪数据流(当错误位于调用栈深处时,要求使用 superpowers:root-cause-tracing 子技能进行反向追踪,快速版本是:坏值源自哪里、谁用坏值调用了这里、持续向上追踪直到找到源头、在源头修复而非症状处修复)。
第二阶段:模式分析。 在修复前找到模式:寻找可工作的示例(在同一代码库中定位类似的可工作代码,什么可工作的代码与损坏的代码相似);对照参考实现(如果实现某个模式,完整阅读参考实现,不要略读,阅读每一行,在应用前完全理解模式);识别差异(可工作与损坏之间有什么不同,列出每一个差异无论多小,不要假设「那不可能有关系」);理解依赖(这需要哪些其他组件、什么设置、配置、环境、它做了什么假设)。
第三阶段:假设与测试。 采用科学方法:形成单一假设(清晰陈述「我认为 X 是根本原因,因为 Y」,写下来,要具体而非模糊);最小化测试(对假设做尽可能小的更改来测试,一次一个变量,不要同时修复多个东西);继续前验证(成功则进入第四阶段,未成功则形成新假设,不要在之上添加更多修复);当你不知道时(说「我不理解 X」,不要假装知道,寻求帮助,做更多研究)。
第四阶段:实施。 修复根本原因而非症状:创建失败测试用例(最简单的复现,如可能则自动化测试,若无框架则用一次性测试脚本,修复前必须有);要求使用 superpowers:test-driven-development 子技能编写正确的失败测试;实施单一修复(解决已识别的根本原因,一次一个更改,不做「顺便」改进,不捆绑重构);验证修复(测试现在通过吗、没有破坏其他测试吗、问题真的解决了吗)。
修复无效时的处理
如果修复无效:停止;计数已尝试了多少次修复;若少于 3 次,返回第一阶段用新信息重新分析;若大于等于 3 次,停止并质疑架构(见下文);不要在未进行架构讨论的情况下尝试第 4 次修复。
3 次以上修复失败:质疑架构
表明架构问题的模式包括:每次修复都在不同地方揭示新的共享状态/耦合/问题;修复需要「大规模重构」才能实施;每次修复都在别处产生新症状。此时应停止并质疑根本:这个模式从根本上合理吗、我们是否「仅凭惯性坚持它」、应该重构架构还是继续修复症状、在尝试更多修复前与人类伙伴讨论。这不是失败的假设,而是错误的架构。
红旗信号
如果发现自己有以下想法,应停止并遵循流程:「先快速修复,稍后调查」「只是试试改 X 看看是否有效」「添加多个更改,运行测试」「跳过测试,我会手动验证」「可能是 X,让我修复它」「我不完全理解但这可能有效」「模式说 X 但我会以不同方式调整」「以下是主要问题:[列出修复而未调查]」、在追踪数据流前提出解决方案、「再试一次修复」(当已尝试 2 次以上)、每次修复都在不同地方揭示新问题。所有这些都意味着:停止,返回第一阶段。若 3 次以上修复失败:质疑架构。
人类伙伴的错误信号
注意这些重定向:「那没有发生吗?」——你未验证就假设了;「它会向我们展示……吗?」——你应该添加证据收集;「停止猜测」——你在未理解的情况下提出修复;「深入思考这个」——质疑根本而非仅症状;「我们卡住了?」(沮丧)——你的方法不奏效。看到这些时:停止,返回第一阶段。
常见借口与现实
技能列出常见借口与现实对照:「问题很简单,不需要流程」——简单问题也有根本原因,流程对简单 bug 很快;「紧急,没时间走流程」——系统化调试比猜测-检查的反复折腾更快;「先试试这个,然后再调查」——第一次修复设定了模式,从一开始就做对;「我会在确认修复有效后写测试」——未测试的修复不会持久,先测试才能证明;「一次多个修复节省时间」——无法隔离哪个有效,会导致新 bug;「参考太长,我会调整模式」——部分理解保证 bug,完整阅读;「我看到问题了,让我修复它」——看到症状不等于理解根本原因;「再试一次修复」(2 次以上失败后)——3 次以上失败等于架构问题,质疑模式而非再次修复。
快速参考
第一阶段根本原因:关键活动为阅读错误、复现、检查变更、收集证据,成功标准是理解是什么和为什么。第二阶段模式:关键活动为寻找可工作示例、比较,成功标准是识别差异。第三阶段假设:关键活动为形成理论、最小化测试,成功标准是确认或新假设。第四阶段实施:关键活动为创建测试、修复、验证,成功标准是 bug 解决、测试通过。
当流程揭示「无根本原因」时
如果系统化调查揭示问题确实是环境性、时序相关或外部的:你已完成流程;记录你调查了什么;实施适当的处理(重试、超时、错误消息);为未来调查添加监控/日志。但 95% 的「无根本原因」案例是不完整的调查。
与其他技能的集成
此技能要求使用:root-cause-tracing——当错误位于调用栈深处时必需(见第一阶段第 5 步);test-driven-development——创建失败测试用例时必需(见第四阶段第 1 步)。互补技能:defense-in-depth——找到根本原因后在多层添加验证;condition-based-waiting——替换第二阶段识别的任意超时;verification-before-completion——在声称成功前验证修复有效。
实际影响
根据调试会话:系统化方法 15-30 分钟修复;随机修复方法 2-3 小时反复折腾;首次修复率 95% 对 40%;引入新 bug 接近零对常见。