BAIZE AI RESOURCE

先定位根因再修复的系统化调试技能

Systematic-debugging

systematic-debugging 是 superpowers 的 AI Skill,要求在处理 Bug、测试失败或异常行为时先调查根因,再提出和验证修复方案。

Systematic-debugging

资源介绍

systematic-debugging 是 obra/superpowers 仓库 skills 目录下的一个 AI Skill,面向需要处理 bug、测试失败、生产故障、性能问题、构建失败和集成问题的开发者。它的核心原则是:在尝试任何修复之前,必须先找到根因,症状式修复被视为失败。技能把调试过程拆成四个必须依次完成的阶段:根因调查(仔细阅读报错、稳定复现、检查近期变更、在多组件系统中加诊断埋点、沿调用栈回溯数据流)、模式分析(寻找可用的相似实现、完整阅读参考实现、列出所有差异、理解依赖)、假设与验证(提出单一假设、做最小改动验证、失败则重新假设而非叠加修复)、实施(先写失败测试用例、只做一处修复、验证修复且不破坏其他测试)。技能还规定,如果连续三次修复都失败,应停止继续尝试并质疑架构本身。它特别强调在时间压力大、看似只需一处快速修复、已经试过多个修复或问题尚未被完全理解时更要使用该流程。

Skill 能力

根因优先的铁律

明确规定未完成根因调查前不得提出任何修复方案,症状式修复视为失败。

四阶段调试流程

依次完成根因调查、模式分析、假设与测试、实施修复,每个阶段完成前不得进入下一阶段。

多组件系统证据收集

在 CI、构建、签名或 API、服务、数据库等多层系统中,先在组件边界加诊断埋点,定位真正出错的层。

数据流回溯

沿调用栈向上追溯错误值的来源,在源头而非症状处修复,配套 root-cause-tracing.md 说明完整方法。

三次失败即质疑架构

若连续三次修复均失败,停止继续打补丁,转而讨论架构是否存在根本性问题。

资源配置

适用平台

Claude Code

支持模型

Claude

调用方式

自动触发

安装与调用

  1. 在遇到 bug、测试失败或异常行为时触发该技能,先不要提出修复方案。

  2. 进入阶段一:仔细阅读报错与堆栈、稳定复现问题、检查近期变更,必要时在组件边界加诊断埋点并回溯数据流。

  3. 进入阶段二:在代码库中寻找可用的相似实现,完整阅读参考实现,列出工作版本与故障版本之间的全部差异。

  4. 进入阶段三:写出单一明确的假设,做最小改动验证,失败则重新提出假设,不在旧修复上叠加新修复。

  5. 进入阶段四:先创建可复现的失败测试用例,再实施针对根因的单一修复,并验证未破坏其他测试。

  6. 若连续三次修复失败,停止继续尝试,转为讨论并质疑当前架构。

使用案例

生产环境 bug 排查

使用场景线上出现异常行为但原因不明

按四阶段流程先复现并收集证据,定位根因后再提交修复,避免盲目打补丁。

多组件流水线故障

使用场景CI、构建、签名等多层系统报错

在各组件边界加入诊断输出,运行一次以确定故障发生在哪一层,再深入该层调查。

多次修复无效

使用场景已经尝试多个修复但问题依旧

停止继续叠加修复,回到阶段一重新分析,若累计三次失败则质疑架构设计。

包含内容

LICENSE-MIT.txt
README-中文安装说明.md
SHA256.txt
systematic-debugging-source.zip

常见问题

这个技能适用于哪些问题?
适用于任何技术问题,包括测试失败、生产 bug、异常行为、性能问题、构建失败和集成问题。
为什么不能直接给出修复方案?
技能的核心原则是必须先找到根因,症状式修复被视为失败,未完成根因调查前不得提出修复。
问题看起来很简单,可以跳过流程吗?
不可以。技能明确指出简单 bug 同样有根因,赶时间或上级要求立即修复时更应使用系统化流程。
连续多次修复都失败怎么办?
若修复次数达到三次仍未解决,应停止继续尝试,转而讨论并质疑架构是否存在根本性问题。