SuperAPI AI 工具集

systematic-debugging

编程与开发

查看项目

更新于 10-16 14:20

技能介绍

用途

Systematic Debugging 用于处理任何技术问题,包括测试失败、生产环境缺陷、异常行为、性能问题、构建失败和集成问题。它的出发点是:随机修补会浪费时间并制造新的缺陷,快速补丁会掩盖底层问题。因此该技能规定了一条“铁律”:在完成根因调查之前,不允许提出修复方案。

主要能力

该技能提供一套四阶段调试流程,每个阶段必须完成后才能进入下一阶段。

阶段一:根因调查。 在尝试任何修复之前,需要仔细阅读错误信息与堆栈跟踪(注意行号、文件路径、错误码),稳定复现问题(若无法复现则应收集更多数据而非猜测),检查近期变更(git diff、提交记录、新依赖、配置变更、环境差异)。在多组件系统中(如 CI → 构建 → 签名,或 API → 服务 → 数据库),需要在每个组件边界添加诊断埋点,记录进入和离开组件的数据、验证环境与配置传递、检查各层状态,先运行一次以收集证据显示问题出在哪一层,再分析证据定位故障组件。当错误位于调用栈深处时,需要沿调用栈向上追踪坏值来源,直到找到源头并在源头修复。

阶段二:模式分析。 在同一代码库中寻找相似的、可工作的代码示例;若在实现某种模式,需完整阅读参考实现而非略读;列出工作版本与故障版本之间的每一处差异,无论多小;理解所需的其他组件、设置、配置和环境假设。

阶段三:假设与测试。 用清晰的一句话陈述假设(“我认为 X 是根本原因,因为 Y”)并写下来,进行最小化改动来验证,一次只改变一个变量,不要同时修复多个问题。验证成功则进入阶段四;失败则形成新假设,而不是在原有修复上叠加更多修复。如果确实不理解,应明确说出“我不理解 X”,而不是假装知道。

阶段四:实施。 先创建失败测试用例(尽可能最简单复现,优先自动化测试,无框架时用一次性脚本),然后实施单一修复,针对已识别的根本原因,一次只做一处改动,不做“顺便改进”或捆绑重构。最后验证测试是否通过、其他测试是否被破坏、问题是否真正解决。

三次修复失败后的架构质疑。 如果已经尝试三次以上修复仍未成功,该技能要求停止,并质疑架构本身:每个修复是否揭示不同位置的新共享状态或耦合问题、是否需要“大规模重构”才能实现、是否每个修复都在别处制造新症状。此时应在与人类伙伴讨论后再尝试更多修复,这被视为架构错误而非假设失败。

红旗信号与常见借口。 技能列出了需要立即停止并回到阶段一的行为信号,例如“先快速修一下,之后再调查”“改一下 X 看看行不行”“同时加多个改动一起跑测试”“跳过测试,我手动验证”“大概是 X,我来修一下”“我不完全理解但可能可行”“再试一次修复”(在已尝试两次以上后)等。同时提供了常见借口与现实的对照表,例如“问题很简单,不需要流程”对应“简单问题也有根本原因,流程对简单缺陷很快”;“紧急,没时间走流程”对应“系统化调试比反复试错更快”;“先试试这个,然后再调查”对应“第一个修复会设定模式,一开始就要做对”。

使用方式

该技能以文档形式提供,作为调试时的流程约束和检查清单使用。配套技术文档包括 root-cause-tracing.md(沿调用栈反向追踪缺陷以找到最初触发点)、defense-in-depth.md(找到根因后在多层添加验证)、condition-based-waiting.md(用条件轮询替代任意超时)。相关技能包括 superpowers:test-driven-development(用于阶段四第一步创建失败测试用例)和 superpowers:verification-before-completion(在声称成功前验证修复有效)。

适用场景

该技能适用于任何技术问题,尤其在以下情况更应使用:时间压力大(紧急情况容易让人猜测)、看起来“只需快速修一下”很明显、已经尝试过多次修复、上一次修复没有生效、不完全理解问题。同时不应跳过的情况包括:问题看似简单(简单缺陷也有根本原因)、时间紧迫(匆忙必然导致返工)、管理者要求立刻修好(系统化方法比反复折腾更快)。

限制

该技能是一套流程规范,要求严格按阶段执行,不做跳跃式修复。它在文档中说明,如果系统化调查后发现问题是真正的环境相关、时序相关或外部原因,则视为流程已完成,应记录调查内容、实施适当处理(重试、超时、错误信息)并添加监控日志;但文档同时指出,95% 的“没有根本原因”案例实为调查不完整。该技能不提供具体代码实现,仅提供流程方法、检查清单、辅助技术文档和相关技能引用。关于收费、价格、平台支持等事实,资料暂未提供。