SuperAPI AI 工具集

systematic-debugging

编程与开发

查看项目

更新于 11-05 17:17

技能介绍

Systematic Debugging 是一个系统化调试技能,核心原则是“在尝试修复之前始终先找到根本原因”。它指出随机修复会浪费时间并产生新缺陷,快速补丁会掩盖底层问题。该技能适用于任何技术问题,包括测试失败、生产环境缺陷、意外行为、性能问题、构建失败和集成问题。

用途与适用场景: 该技能用于指导开发者在遇到任何缺陷、测试失败或意外行为时,按照结构化流程进行调试,避免猜测式修复。特别适合时间压力大、问题看似简单、已经尝试多次修复无效、或对问题理解不充分的情况。技能强调即使问题简单或时间紧迫也不应跳过流程。

主要能力与四阶段流程: 技能定义了必须依次完成的四个阶段。

阶段一:根因调查。在尝试任何修复之前,仔细阅读错误信息和警告,完整阅读堆栈跟踪,记录行号、文件路径和错误代码;稳定复现问题,明确触发步骤并确认是否每次都发生,若无法复现则收集更多数据而非猜测;检查近期变更,包括 Git diff、最近提交、新依赖、配置变更和环境差异;在多组件系统中,在每个组件边界添加诊断日志,记录进入和退出组件的数据,验证环境和配置传播,检查各层状态,运行一次以收集证据确定故障层,然后分析证据并调查具体组件;当错误位于调用栈深处时,追踪数据流,找到错误值的起源、调用者,一直向上追踪到源头,在源头修复而非症状处修复。

阶段二:模式分析。寻找同一代码库中类似的可工作代码;如果实现某种模式,完整阅读参考实现,不要略读;识别工作代码与故障代码之间的每一个差异,无论多小;理解依赖关系,包括所需的其他组件、设置、配置、环境和假设。

阶段三:假设与测试。形成单一假设,明确陈述“我认为 X 是根本原因,因为 Y”,并写下来;进行最小化测试,只做一个变量的最小可能更改来测试假设;验证结果,如果有效则进入阶段四,如果无效则形成新假设,不要在原有修复上叠加更多修复;当不确定时,承认“我不理解 X”,不要假装知道,寻求帮助或进一步研究。

阶段四:实施。创建失败测试用例,尽可能简单复现,最好自动化测试,如果没有框架则使用一次性测试脚本,修复前必须拥有该测试;实施单一修复,针对已识别的根本原因,一次只做一个更改,不捆绑重构或“顺便”改进;验证修复,确认测试通过、其他测试未被破坏、问题真正解决。如果修复无效,停止并计数:如果尝试少于三次,返回阶段一用新信息重新分析;如果三次或以上失败,停止并质疑架构,不要在没有架构讨论的情况下尝试第四次修复。技能指出三次以上修复失败的模式表明架构问题,例如每次修复都在不同地方揭示新的共享状态或耦合问题、修复需要大规模重构、每次修复都在别处产生新症状,此时应与人类伙伴讨论根本设计而非继续修复症状。

红 flags 与常见合理化: 技能列出了需要停止并返回阶段一的思维信号,例如“先快速修复,以后再调查”、“只是试着改 X 看看行不行”、“同时添加多个更改然后运行测试”、“跳过测试,我手动验证”、“可能是 X,让我修复它”、“我不完全理解但这可能有效”、“模式说 X 但我将以不同方式调整”、“以下是主要问题:[未经调查列出修复]”、在追踪数据流之前提出解决方案、“再试一次修复”(已经尝试两次以上)、每次修复都在不同地方揭示新问题。技能还提供了常见合理化借口与现实的对照表,例如“问题简单,不需要流程”对应“简单问题也有根本原因,流程对简单缺陷很快”;“紧急,没时间走流程”对应“系统化调试比猜测式反复尝试更快”;“先试这个,然后再调查”对应“第一次修复设定了模式,从一开始就做对”;“确认修复有效后再写测试”对应“未测试的修复不会持久,先测试才能证明”;“一次多个修复节省时间”对应“无法隔离哪个有效,会导致新缺陷”;“参考太长,我会调整模式”对应“部分理解必然导致缺陷,完整阅读”;“我看到问题了,让我修复它”对应“看到症状不等于理解根本原因”;“再试一次修复”(两次失败后)对应“三次以上失败等于架构问题,质疑模式而非再次修复”。技能还列出了人类伙伴的信号,例如“那不是没发生吗?”表示你未经核实就假设;“它会向我们展示……吗?”表示你应该添加证据收集;“停止猜测”表示你在不理解的情况下提出修复;“超级思考这个”表示质疑根本而非仅症状;“我们卡住了?”(沮丧)表示你的方法不奏效。

支持性技术与相关技能: 技能附带了支持性技术文档:root-cause-tracing.md 用于通过调用栈向后追踪缺陷以找到原始触发点;defense-in-depth.md 用于在找到根本原因后在多层添加验证;condition-based-waiting.md 用于用条件轮询替代任意超时。相关技能包括 superpowers:test-driven-development 用于编写失败测试用例(阶段四第一步),以及 superpowers:verification-before-completion 用于在声称成功前验证修复有效。

限制与注意事项: 技能说明,如果系统化调查发现问题是真正的环境性、时序相关或外部问题,则已完成流程,应记录调查内容,实施适当的处理(重试、超时、错误消息),并添加监控/日志以供未来调查。但技能指出 95% 的“无根本原因”情况是调查不完整。技能强调不要在没有完成阶段一的情况下提出修复,违反流程的字面要求就是违反调试精神。

使用方式: 该技能以技能文档形式提供,用户可在遇到任何技术问题时调用,按照四阶段流程逐步执行。具体安装命令和平台集成方式暂未提供。