SuperAPI AI 工具集

systematic-debugging

编程与开发

查看项目

更新于 11-11 16:18

技能介绍

systematic-debugging 是一个面向技术问题排查的技能,适用于遇到任何 bug、测试失败或异常行为、且准备提出修复方案之前的场景。资料指出,随意修复既浪费时间又会产生新 bug,快速打补丁只会掩盖底层问题,因此核心原则是:必须先找到根本原因再尝试修复,只处理表面症状属于失败。

适用场景包括测试失败、生产环境 bug、异常行为、性能问题、构建失败和集成问题。资料特别强调,在时间紧迫、看似只需“快速修一下”、已经尝试过多次修复、上次修复无效或尚未完全理解问题时,更应使用该技能;问题看似简单、时间仓促或上级要求立刻修复时也不应跳过流程。

该技能要求依次完成四个阶段。第一阶段是根因调查:仔细阅读错误信息和完整堆栈,记录行号、文件路径与错误码;稳定复现问题并记录具体步骤,无法复现时继续收集数据而非猜测;通过 git diff、近期提交、新依赖、配置变更和环境差异检查近期改动;在 CI→构建→签名、API→服务→数据库等多组件系统中,先在每个组件边界添加诊断日志,确认数据进出与环境配置传递,运行一次以定位失败层级,再分析该组件;错误位于调用栈深处时,沿数据流向上追溯错误值的来源,并在源头而非症状处修复。第二阶段是模式分析:在同一代码库中寻找可用的同类示例,完整阅读参考实现的每一行,逐一列出可用与出问题的实现之间的所有差异,并理解其依赖、配置、环境和假设。第三阶段是假设与验证:明确提出“我认为 X 是根因,因为 Y”的单一假设,以最小改动、单一变量进行测试;若无效则提出新假设,不在旧修复上叠加。第四阶段是实施:先创建最简单的失败测试用例(有条件时自动化),针对已确认的根因做单一修改,避免顺带重构,然后验证修复生效且其他测试未被破坏。

若修复失败,应停止并统计尝试次数:少于三次时带着新信息回到第一阶段重新分析;三次及以上则质疑架构——例如每次修复都在别处暴露新的共享状态或耦合、需要大规模重构、或不断产生新症状——此时应与人类伙伴讨论是否重构,而不是继续尝试第四次修复。资料还列出应立即停止的危险信号,如“先快速修复以后再调查”“改改看行不行”“一次加多个改动”“跳过测试手动验证”“大概是 X 直接修”等,以及人类伙伴可能给出的纠正信号,如“是不是没发生?”“停止猜测”“深入思考一下”。

该技能附带根因追踪、纵深防御、基于条件等待等支撑技术文档,并关联测试驱动开发(用于编写失败测试)和完成前验证(在宣称成功前确认修复有效)等技能。资料称其实际效果为:系统化方法 15—30 分钟即可修复,随机修复需 2—3 小时反复试错;首次修复率为 95% 对 40%,引入新 bug 接近零。限制方面:仅在任务明显匹配上述范围时使用;输出不能替代针对具体环境的验证、测试或专家评审;若缺少必要输入、权限、安全边界或成功标准,应停止并请求澄清。