用途:Systematic Debugging 是一套面向任何技术问题的四阶段调试框架,来自 obra/superpowers,适用于遇到 bug、错误或非预期行为时,防止随机尝试修复。核心原则是“未先调查根因,不得动手修复”,因为随机修复会引入新 bug,理解必须先于解决方案。
主要能力(四个阶段):
- 根因调查:在尝试任何修复前,仔细阅读错误信息(完整堆栈、错误码与描述、时间戳与上下文);稳定复现问题(记录确切步骤、识别触发条件、注意环境因素);检查近期变更(提交、依赖更新、配置变更);收集诊断证据(在组件边界加日志、检查每步输入输出、沿数据流回溯到源头)。
- 模式分析:寻找可正常工作的相似代码,搜索相关功能与既有模式,完整阅读参考实现而非略读;对比正常与故障代码的差异与假设变化;理解依赖关系(该代码依赖什么、什么依赖它)。
- 假设与验证:形成单一且具体的假设(如“错误因 X 发生”,而非罗列多种可能);以最小改动测试,一次只改一个变量,不合并多个修复;诚实接受结果,假设错误就重新提出,不强行套用证据;在真正调查并收集证据后仍卡住时再求助。
- 实现:先创建会失败的测试用例(能复现 bug、修复后通过);实施单一修复,只针对根因,不顺带修“附近”问题;验证修复(测试通过、无回归、问题解决)。
三修复规则:若连续 3 次修复失败,应停止并质疑架构,这通常意味着架构问题而非实现 bug,或对系统的心理模型有误,需退后重新评估,不要继续尝试更多修复。
关键红线:在理解问题前提出修复、同时加入多个改动、为“快速修复”跳过调查、3 次以上失败尝试、说“我们就试试这个”,出现这些情况应停止并重新开始调查。
使用方式:按清单推进——调查(读完整错误/堆栈、稳定复现、检查近期变更、加诊断日志、追踪数据流);分析(找到相似可用代码、对比正常与故障、理解全部依赖);假设(形成单一具体假设、最小改动测试、诚实接受结果);修复(创建失败测试、实施单一修复、验证有效且无回归)。
适用场景:任何技术问题的调试,包括登录静默失败等示例(通过日志发现邮箱归一化正则错误地去掉 @ 符号)。
限制:资料未提供安装命令、平台支持、收费或价格信息,暂未提供。