floatboat
打开导航菜单

Systematic Debugging by Jesse Vincent

使用 Superpowers 的 Systematic Debugging，在提出修复前先调查故障。复现行为，比较正常与异常路径，检验具体解释，再验证针对根因的修改，避免在未解决的问题上不断叠加推测性改动。

沿系统边界追查故障原因

修复前提供完整故障和相近成功样例，让请求沿组件边界检查证据并验证一个因果假设。修复后重新运行原始症状，避免在已有失败尝试之上继续添加缺乏支持的补丁。

比较正常与失败环境、流水线阶段及实际错误输出。

复制请求，在 Floatboat 新对话中粘贴，并提供所需资料。

下载 Floatboat

带入 Floatboat 的请求

请求可预览和复制，不会从此处自动发送。

参考来源: Systematic Debugging
https://github.com/obra/superpowers/blob/main/skills/systematic-debugging/SKILL.md

先阅读原始说明并核对当前环境与依赖。需要安装或连接新工具时，先提出方案。

我的任务:
使用 Superpowers Systematic Debugging 调查仅 CI 出现的构建失败，先比较流水线环境传递，再提出修复并验证原始任务。

期望交付:
包含假设验证的根因调查，并重新运行原来失败的任务。

关于 Systematic Debugging

Systematic Debugging 是 Superpowers 的根因调查 Skill，由 Jesse Vincent 及项目贡献者维护。它将工作分为证据收集、模式比较、假设检验和实施四个阶段，要求 Agent 先读错误、复现失败、检查近期变化，并观察组件边界上的数据，再选择修复。每次通过小测试检验一个解释；实施阶段需要失败复现与结果验证。连续多次修复无效时，应转向架构讨论，而不是继续盲改。完整流程引用配套测试与完成验证 Skills，实际使用仍依赖访问故障发生环境及必要的诊断工具。

Systematic Debugging Skill的使用场景

反复改动仍未消失的症状，需要重新检查原因，而不是继续猜测补丁。Systematic Debugging 通过正常对照、边界输入输出和架构假设核验，帮助定位真正失败的位置。

测试意外失败

测试意外失败时，先阅读完整日志、触发输入和相近的成功样例，再考虑修改代码。比较两条路径并验证因果解释，而不是直接修补表面症状。修复后重新运行原始失败测试，让根因判断能够与实际行为对应。

流水线在组件之间失败

定位管线故障时，逐一比较组件边界的输入和输出，结合阶段参数及上下游日志，查找最早偏离预期的位置。保留该边界的证据，使诊断能够指出真正出现问题的层级，而不是只记录后续表现出来的症状。

多次尝试修复无效

多次修复没有成功时，应重新检查假设，而不是继续叠加未经验证的补丁。比较每次尝试实际改变了什么、观察到了什么，再讨论可能的架构原因。下一轮修改前先重新评估结构性解释，避免在缺乏因果依据时重复试错。

对照成功与失败环境

故障只在某台机器或管线阶段出现时，需要将配置与已知成功情况比较。追踪最早有意义的差异，检验它能否解释症状，并保留日志和边界输入。修复应针对这个原因，在两种环境复测，而不是用无关回退隐藏差异。

如何按根因调查故障

正常对照和完整故障证据共同支撑因果判断。收集复现背景后，用最小改动检验单一假设，再实施有依据的修复；原始症状与相关检查均需重跑，才能判断原因是否消除。

  1. 收集证据与正常模式

    复现错误、检查近期变化并比较正常路径，多组件问题可添加针对性边界观察。

  2. 检验一个解释

    提出具体假设并进行最小有效测试，每次改变一个变量，评估后再选择其他解释。

  3. 实施并验证根因修复

    保留失败复现、实施有依据的修复并重跑相关检查，连续失败时转入设计讨论。

探索更多 Agent Skills

查看其他 Skill 指南，并在使用前核对原始来源。

Systematic Debugging 常见问题

它与 Matt Pocock 的 Diagnosing Bugs 有何不同？
它们属于不同发布者的独立流程。Superpowers 使用四阶段及配套测试与验证，Matt 当前流程尤其强调可失败的紧密反馈循环和最小复现。
可以立刻应用看起来明显的修复吗？
该 Skill 要求先调查根因。看似合理的改动不等于证据，应说明它为何解决观察到的故障并验证行为。
四个阶段是什么？
分别是根因调查、模式分析、假设检验和实施，各阶段为下一阶段提供证据。
连续几次修复失败后应怎样？
原文要求三次及以上修复无效后停下来审视架构，不再继续增加推测补丁。
引用了哪些配套 Skills？
实施阶段引用 test-driven-development 编写失败测试，以及 verification-before-completion 检查最终结果，应通过 Superpowers 集成保留它们。
测试通过就一定修复了吗？
需要确认测试确实复现用户症状，并在修复后重跑原始流程。相近条件通过可能遗漏根本故障。
无法访问故障环境时能诊断吗？
它可以组织调查，但缺少复现证据会限制结论。应提供适当脱敏日志或代表环境，并将未证实解释保留为假设。
Codex App 与 Codex CLI 如何分别安装？
Codex App 在侧栏 Plugins 中找到 Coding 下的 Superpowers，点击 + 并按提示安装；Codex CLI 运行 /plugins，搜索 Superpowers 并选择 Install Plugin。两者是官方插件市场的不同界面入口。