systematic-debugging

systematic-debugging skill 概览

systematic-debugging skill 是一套结构化的调试工作流，适合希望减少“猜着修”、更快定位根因的开发者和智能体。它的核心规则很简单：先调查，再改代码。因此，它特别适合处理测试失败、偶发性问题、线上 bug、构建异常，以及各种“看起来能快速修一下”，但实际上很可能掩盖真实原因的集成问题。

谁最适合用这个 skill

如果你符合下面这些情况，就很适合用 systematic-debugging：

• 修过几次还是没修好，或者只能修掉一半
• 在时间压力下排查问题
• 需要 AI 助手先放慢节奏做调查，而不是直接去补症状
• 想要一套可重复使用的流程来处理 bug、flaky tests 和异常行为

尤其是在问题表面看起来很明显，但你还不知道它为什么会发生时，这个 skill 很有价值。

这个 skill 真正帮你完成的是什么工作

它真正要解决的，不是“产出一个修复方案”，而是：

1. 复现问题
2. 追踪原因
3. 一次验证一个解释
4. 最后才实施有针对性的修复

表面上看这会更慢，但实际通常能减少返工、降低修补失败率，也能避免因为拍脑袋修改而引入新 bug。

systematic-debugging 的不同之处

很多普通 prompt 都是从“症状”直接跳到“方案”。而 systematic-debugging skill 明确反对这种做法。这个 repo 强调一种接近 “Iron Law” 的工作方式：在没有完成根因调查之前，不要动手修。

而且，仓库里的配套文件让它比一般的调试清单更实用：

• root-cause-tracing.md：适合处理“报错点离真实源头很远”的问题
• condition-based-waiting.md：适合处理因任意延时导致的 flaky async tests
• defense-in-depth.md：帮助你把一次性的校验修补，升级成更稳固的结构性防护
• find-polluter.sh：用于隔离会泄漏文件或状态的测试

最适合处理的问题类型

systematic-debugging for Debugging 特别适合以下场景：

• 你暂时解释不清楚的测试失败
• CI 中的 flaky tests
• 之前修过但没彻底修好的 bug
• 报错出现在调用栈很深的位置
• 脏状态、文件泄漏、路径错误、竞争条件、时序问题

哪些情况下它不太适合

只有在任务本质上并不是调试时，才可以跳过它，比如：

• 很直接的功能开发
• 没有故障行为需要解释的常规重构
• 纯视觉或文案类改动

即便如此，如果你面对的是“unexpected behavior”，systematic-debugging 通常仍然是更稳妥的起点。

如何使用 systematic-debugging skill

systematic-debugging 的安装方式

如果你使用的是这个生态里常见的 Skills CLI 模式，可以这样安装：

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

安装后，你可以在 agent 环境中直接调用它；也可以通过阅读 skill 文件夹中的源码，手动按它的流程来使用。

建议先读这些文件

如果你想快速获得高信息密度的 systematic-debugging guide，建议按下面顺序阅读：

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

这个顺序的原因是：

• SKILL.md 给出了必须遵守的四阶段流程
• root-cause-tracing.md 适合处理“症状出现在下游”的情况
• condition-based-waiting.md 提供了 flaky async tests 的具体修法模式
• defense-in-depth.md 帮你把最终修复做得更稳
• find-polluter.sh 是隔离测试污染的实用工具

这个 skill 需要你提供什么输入

systematic-debugging usage 的效果，很大程度上取决于你提供的信息质量。最好给它这些内容：

• 精确的错误信息
• stack trace
• 复现步骤
• 预期行为和实际行为
• 环境细节，比如 OS、runtime、test runner、只在 CI 出现还是本地也出现
• 最近的代码变更
• 问题是稳定复现还是偶发
• 你已经尝试过什么

如果缺少这些信息，模型就更容易开始猜。

如何把一个粗糙的 bug 描述改成高质量 prompt

弱 prompt：

Test is failing. Help fix it.

更强的 prompt：

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

这个 prompt 更有效，因为它明确要求先输出调查结果，再进入实现。

一个实用的 prompt 模板

你可以用下面这个结构来做 systematic-debugging usage：

• Issue：失败的是什么
• Reproduction：精确命令或复现步骤
• Evidence：日志、trace、截图、失败断言
• Scope：本地、CI、单机、所有环境
• Recent changes：commit、依赖升级、配置改动
• Constraints：不能改 API、需要最小 patch、有截止时间等
• Request：先调查 root cause，再提出一个修复方案

示例：

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

按顺序执行四阶段工作流

这个 repo 的核心是四个阶段。实际使用时，建议这样执行：

1. Root cause investigation
   仔细阅读错误信息，稳定复现，检查变更点，并收集证据。
2. Pattern analysis
   识别是否存在时序、环境、输入形态、状态泄漏或调用链相关模式。
3. Hypothesis testing
   一次只提出并验证一个解释。不要同时改多个变量。
4. Implementation
   只有在证据已经支持某个原因之后，才实施修复并验证结果。

如果 Phase 1 做得不扎实，后面每一步都会变差。

如何用 systematic-debugging 处理 flaky tests

这个 repo 在这一点上给出的帮助非常落地。如果测试里依赖 sleep、setTimeout 或任意等待时间，建议重点看 condition-based-waiting.md 和 condition-based-waiting-example.ts。

关键转变是：

• 差的模式：猜异步任务大概要跑多久
• 更好的模式：等待能够证明任务完成的条件出现

这很重要，因为很多“随机失败”，本质上都是被时序猜测掩盖起来的 race condition。

当症状出现在下游时怎么用 systematic-debugging

如果错误出现在调用栈很深的位置，或者离错误数据真正产生的地方很远，就该用 root-cause-tracing.md。基本流程是：

• 先确定眼前报错的那一行
• 往上追一层调用者
• 继续往上追，直到找到错误状态第一次出现的位置
• 在源头修，不要只在崩溃点打补丁

这是 systematic-debugging skill 里最有价值的部分之一，因为很多 bug 都只是更早期非法状态的结果，而不是发生在报错位置本身。

如何使用 polluter finder

如果你的测试会残留文件、目录或某种状态，在自己随手写循环脚本之前，建议先看 find-polluter.sh。

使用模式：

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

脚本里的示例：

./find-polluter.sh '.git' 'src/**/*.test.ts'

当真正导致失败的是隐藏的测试污染，而不是表面上失败的那个测试时，这个工具特别有用。

首次安装和使用的推荐流程

一套可靠的 systematic-debugging install 与首次使用流程如下：

1. 安装 skill
2. 阅读 SKILL.md
3. 收集精确的失败证据
4. 先让 agent 调查，不要修
5. 选出证据最充分的假设
6. 只验证这个假设
7. 实施一个聚焦的修复
8. 如果 bug 源于非法数据或多个入口路径，再补上 validation 或 defense-in-depth

这样做可以避免最常见的失败模式：在还没真正理解故障之前就开始改代码。

使用这个 skill 时不要做什么

不要让 systematic-debugging 去做这些事：

• 一上来就头脑风暴很多修法
• 在还没复现 bug 之前大改代码
• 不解释原因，只求“先把测试跑过”
• 一次性补多个疑似原因

这些捷径和该 skill 的设计目标是正面冲突的，也会明显拉低输出质量。

systematic-debugging skill 常见问题

systematic-debugging 只适合复杂 bug 吗？

不是。这个 repo 的观点是：即使是看起来简单的问题，也有根因。恰恰是在问题“简单到让人想顺手补一下”的时候，这个 skill 最能体现价值。

它和普通的调试 prompt 有什么区别？

普通 prompt 往往偏向速度，也容易鼓励猜测式修复。systematic-debugging 会强制模型把调查、假设和实现分开处理。这样通常能减少错误 patch，也能给出更清晰的解释。

systematic-debugging 对新手友好吗？

友好，前提是你能提供具体证据。它的流程虽然严格，但步骤并不难理解：复现、检查、追踪、一次验证一个想法、最后再修。对新手来说，它反而可能更有帮助，因为它能阻止随机试错。

什么情况下不该用 systematic-debugging？

以下任务不适合把它当作首选模式：

• 功能创意发散
• 架构 brainstorming
• 与故障无关的代码生成
• 没有异常行为需要解释的纯视觉调整

当你面对的是“有东西坏了”，并且你需要的是原因，而不只是一个 patch 时，才应该用它。

systematic-debugging 能处理只在 CI 里出现的失败吗？

能。它很适合处理只在 CI 出现、或对负载敏感的问题，因为它会推动你去比较环境差异、复现触发条件，并检查时序和状态假设，而不是靠猜。

它能帮助处理 flaky async tests 吗？

可以，而且这个 repo 在这方面比一般资料更强。condition-based-waiting.md 和配套的 TypeScript 示例文件，提供了一条很具体的路径，帮助你从任意等待转向 condition-based synchronization。

这个 skill 提供的是工具，还是只有方法建议？

以流程指导为主，但也带了一些具体的配套文件。最实用的辅助工具是 find-polluter.sh，而 condition-based waiting 的示例对于某些 TypeScript 测试场景可以直接复用。

我可以在任意技术栈里使用 systematic-debugging 吗？

大体可以。核心方法和技术栈无关。示例更偏向 TypeScript、shell 和测试工作流，但调查与定位根因的过程适用于大多数语言和框架。

如何改进 systematic-debugging skill 的使用效果

在请求修复前，先提供更好的证据

最大的提升杠杆就是输入质量。想获得更好的 systematic-debugging 结果，至少尽量提供：

• 一个精确的复现命令
• 一段完整准确的错误信息
• 一个最小失败测试或文件
• 最近改了什么
• 这个问题是否总能复现

这样它才能基于证据工作，而不是基于推测。

先要求调查输出，再进入实现

高质量 prompt 会明确阻止过早修复。例如：

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

这样做能提升回答质量，因为它在“读症状”和“改代码”之间加了一个必要的检查点。

强制一次只验证一个假设

常见失败模式之一，就是把多个可能原因混在一个 patch 里一起改。你可以明确要求输出：

• 当前最优先的假设
• 能最小化否证它的测试
• 什么结果会构成确认

这样工作流才会真正符合这个 skill 的设计意图。

在 flaky test 场景下优化 prompt

当你用 systematic-debugging for Debugging 处理 flaky tests 时，尽量补充这些信息：

• 通过/失败的大致频率
• 是否与并行执行或 CI 有相关性
• 是否使用了 sleeps、waits、retries 或 polling
• 测试到底在观察哪个具体事件或状态

这些信息能显著帮助模型判断 condition-based-waiting.md 是否就是当前最相关的配套模式。

不要只看 SKILL.md，也要用靠近源码的配套文件

如果第一轮输出感觉太泛，可以直接把模型引向这些支持文档：

• root-cause-tracing.md：处理下游症状
• condition-based-waiting.md：处理时序 / race 问题
• defense-in-depth.md：处理验证和防护策略
• find-polluter.sh：处理测试污染

这个 skill 在 agent 同时利用这些专门材料时，效果会明显好于只看主流程说明。

第一轮之后继续收窄范围

如果第一轮结果太宽泛，可以进一步补充：

• 要重点检查的具体子系统
• 疑似脏数据进入系统的边界位置
• 问题最早出现的 commit
• 最小失败复现

宽泛的调试请求，通常只会得到宽泛的调试计划；范围越收窄，根因定位通常越有效。

不只改进诊断，也要改进最终修复

找到根因之后，可以进一步要求输出：

• 最小修复方案
• 一个回归测试
• 一层防止再次发生的 validation

这正是 defense-in-depth.md 发挥作用的地方。如果 bug 来源于非法输入或可以被绕过的前提假设，单个 patch 往往不够。

留意这些常见失败模式

糟糕的 systematic-debugging usage 往往来自这些问题：

• 错误文本不完整
• 没有可靠复现
• 太早要求给修复方案
• 每次测试运行之间改了太多东西
• 把第一个“看起来合理”的解释当成已证实事实

只要避开这些坑，这个 skill 的价值通常会明显高于普通的“帮我 debug 一下”式 prompt。