systematic-debugging

系统化调试

斜杠命令用法

通过 /superpowers:systematic-debugging "<symptom>" 调用，或在其他技能检测到修复 Bug 相关表述时自动加载。

作为斜杠命令调用时：将 $ARGUMENTS 作为症状说明，并立即从阶段 1 开始。不要编写设计文档或任务文件；交付内容是 修复 + 能捕获回归的测试，而不是 docs/plans/ 文件夹。

输出规范：完成每个阶段时，立即报告发现。最后给出：(a) 一句话说明根本原因；(b) 修复差异摘要；(c) 回归测试路径。

建议：在 /goal 中运行

在 Claude Code 内置的 /goal（v2.1.139+）下启动，以便多轮“假设 → 测试 → 修复”调查持续进行，直到真正修复回归：

/goal "Claude has narrated the three-part completion output (root-cause one-liner, fix diff summary, regression-test path) with the regression test passing" /superpowers:systematic-debugging "<symptom>"

/goal 是由用户输入的外层包装命令（技能无法在运行过程中自行启用），其评估器只判断 Claude 在对话记录中叙述的内容——请根据叙述的输出设置条件（打印的测试运行结果、三部分摘要），而不是文件系统状态。完整语义和条件措辞：../../skills/references/goal-wrapper.md。

严重：退出检查（在阶段 1 之前运行）

检查 $ARGUMENTS 中是否包含“明确指出根本原因 + 明确指出修复方法”的信号。仅当以下条件全部满足时，才退出——跳过 4 阶段流程，直接应用修复并编写回归测试：

• $ARGUMENTS 指出了具体的根本原因（文件:行号、配置键或具体值），并且
• $ARGUMENTS 指出了具体的修正措施（“将 X 改为 Y”“添加缺失的标志”“修正拼写错误”），并且
• 修复仅涉及单个文件或单个字符串替换

会触发退出的示例：

• “cookie 域名是 .foo.com，应该是 foo.com——修复它”
• “api.ts:42 缺少 await，加上它”
• “deploy.yaml 中错误的环境变量名 DB_HOST 应该是 DATABASE_HOST”

不会触发退出的示例（继续阶段 1）：

• “测试在 CI 中失败，但在本地通过”（仅有症状，没有根本原因）
• “这个很慢”（没有假设）
• “我觉得是缓存的问题，你能检查一下吗？”（有假设，但根本原因尚未确认）

退出时的响应（逐字输出，然后应用修复 + 编写能捕获 Bug 的回归测试）：

检测到明确指出的根本原因和修复方法。跳过 4 阶段流程（该流程针对未知根本原因而设计）。直接应用修复并编写回归测试。若要强制执行完整流程，请重新调用 /superpowers:systematic-debugging --force "<symptom>"。

用户传入 --force（$ARGUMENTS 中的字面标记）时，跳过此退出检查，无条件继续阶段 1。

非退出路径仍须遵守铁律——只有当用户已经完成根本原因调查，并将结论告知 Claude 时，才会触发退出。

概述

**核心原则：**任何修复尝试之前都必须先调查根本原因——随机修复会浪费时间、掩盖深层问题并引发新 Bug。违反流程的字面要求，就是违背调试的本意。

严重：铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

未完成阶段 1 前不得提出修复方案。每个阶段都必须结束后才能进入下一阶段。违反此规则会导致尝试修复掩盖根本原因——这正是本技能旨在防止的失败模式。如果你发现自己在没有阶段 1 完整证据的情况下提出修复方案，请立即停止并返回阶段 1。

适用场景

适用于任何技术问题：测试失败、生产环境 Bug、意外行为、性能问题、构建失败。

**尤其适用的情况：**时间压力让人想要猜测、看似显而易见的“快速修复”、先前的修复无效，或问题尚未完全弄清。

不要因为问题看起来简单、时间紧张或情况紧急而跳过流程——请参阅 ./references/rationalizations-and-guardrails.md，了解这些情况为何都是陷阱。

四个阶段

阶段 1：根因调查

尝试修复之前：

0. 查阅记忆——每当触发“放弃检查”时，都会跳过此记忆读取步骤（与“放弃检查”会跳过从阶段 1 开始的其他所有步骤相对应）：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active，按症状关键词筛选，并在步骤 1 前阅读最匹配的 2-3 项。

1. 仔细阅读错误消息——完整阅读堆栈跟踪；记下行号、文件路径和错误代码。消息和警告中往往包含解决方案。

2. 稳定复现问题——找出准确的操作步骤，并确认问题能否稳定触发。如果无法复现，应收集更多数据，而不是猜测。

3. 检查近期变更——查看 git diff 和近期提交、新依赖、配置变更及环境差异。

4. 收集多组件系统的证据（CI -> 构建 -> 签名、API -> 服务 -> 数据库）——提出修复方案前，先添加诊断检测：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   实例（CI 工作流 → 构建 → 签名）：./references/root-cause-tracing.md §多层检测实例。

5. 追踪数据流——当错误出现在调用栈深处时：找出错误值的来源，确定是谁调用了它，继续向上追踪，直到找到源头；从源头修复，而不是处理症状。完整的反向追踪技巧：./references/root-cause-tracing.md。

阶段 2：模式分析

应先识别模式，再进行任何修复：

1. 查找正常运行的示例——在同一代码库中查找类似且正常运行的代码。
2. 对照参考实现——如果要实现某种模式，请先完整阅读参考实现（逐行阅读，不要略读），再应用该模式。
3. 找出差异——列出正常代码与出错代码之间的所有差异；不要认定细微差异无关紧要。
4. 了解依赖项——此操作所需的其他组件、设置、配置和环境，以及该模式所依赖的假设。

阶段 3：假设与测试

应用科学方法：

1. 提出单一假设——清晰、具体地表述：“X 是根因，因为 Y”。
2. 进行最小化测试——只做尽可能小的改动，每次只改变一个变量；不要同时修复多个问题。
3. 确认后再继续——已确认：进入阶段 4；未确认：提出新假设。不要在此基础上叠加更多修复。
4. 理解不足时——坦诚说明，进一步调查，并寻求帮助。

阶段 4：实现

修复根本原因，而非表面症状：

1. 创建失败测试用例 — 尽可能简单地复现问题；如果可以，编写自动化测试；如果没有测试框架，则编写一次性脚本。必须先创建测试，再进行修复。

2. 实施单一修复 — 一次只处理已确定的根本原因，只做一项更改；不要顺手改进，也不要捆绑重构。

3. 验证修复 — 测试现在通过了吗？没有其他测试被破坏吗？问题真的解决了吗？

4. 如果修复无效 — 停下来，统计已尝试的修复次数。如果 < 3：返回阶段 1，根据新信息重新分析。如果 >= 3：质疑架构。

5. 3 次或更多修复失败后质疑架构 — 如果每次修复都会在其他地方暴露新的共享状态／耦合问题、需要“大规模重构”，或引发新的症状，就停下来质疑根本问题：这种模式可靠吗？是否只是因为惯性而继续沿用这种方法？是否应该重构架构，而不是修复表面症状？在尝试更多修复前，先与人类伙伴讨论——这不是假设失败，而是架构有误。

6. 记录记忆（有条件 — 此技能唯一会触及 docs/ 的环节，不是新阶段或新提交）

   此步骤沿用现有的“3 次或更多修复失败”触发条件作为主要门槛：触发后，在与修复相同的提交中执行记忆 upsert；或者，无论尝试修复的次数多少，只要明确遇到跨领域陷阱，也会独立触发；否则不做任何操作。

   触发时：写入 docs/memory/<category>_<slug>.md（通常 category: pitfall；如果架构质疑的结论是需要重新设计，则用 decision），复用内联计划的六行格式作为 Fact/Why 内容，并注明 source: commit:<short-sha>。然后运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category <category>，并与修复和回归测试一同暂存到同一个提交中——不单独提交，也不增加额外交付物。

复杂 Bug：内联计划摘要（不写入文件）

对于复杂 Bug，在进行任何代码更改之前，先在内联记录简洁计划——绝不创建 docs/plans/ 文件夹或 BUGFIX_PLAN.md 文件（原因：./references/rationalizations-and-guardrails.md §Why the Complex-Bug Plan Is Inline）。内联计划是此技能在阶段 2 至阶段 4 中遵循的约定，也是用户在修复后审查的内容。

何时需要内联计划

符合以下任一情况时，必须在编辑前执行内联计划步骤：涉及多个组件（多个文件／模块／子系统）、影响架构（设计、约定、接口）、存在多个有效方案、可能影响无关功能、需要超出最小补丁范围的重构，或阶段 1 结束后根本原因仍不明确。

内联计划格式

完成阶段 1（根本原因调查）后，在当前轮次的输出中内联记录计划（不要写入文件），使用以下六行格式，然后直接进入阶段 2，并以此计划为约定：

ROOT CAUSE: <one-line summary from Phase 1 evidence>
FIX STRATEGY: <what change resolves the cause, in one sentence>
FILES: <comma-separated paths that will be modified>
TESTS: <regression test path(s) + scenario name>
RISKS: <one line — side effects, blast radius, or "low: localized to <subsystem>">
ALTERNATIVES: <one line — rejected approaches + why>

不要暂停等待批准。此计划在阶段 2 至阶段 4 中始终作为约定；如需偏离，必须重新执行阶段 1 并记录新的六行格式——不要在处理中悄悄更改修复方案。如果证据不足以有把握地填写任何一行，请先返回阶段 1 的第 4 步；绝不要用含糊的描述掩盖证据不足。

对于简单 Bug： 直接继续阶段 2 至阶段 4，无需内联计划。

危险信号

以下思维模式表明违反了流程——返回阶段 1：

• “先快速修复，之后再调查”
• “试着改一下 X，看看是否有效”
• “做几处改动，然后运行测试”
• “跳过测试，我会手动验证”
• “问题可能出在 X，我来修复”
• “我还没完全弄懂，但这样或许可行”
• “虽然模式指出 X，但我会用另一种方式调整”
• 尚未追踪数据流就提出解决方案
• “再试着修复一次”（此前已尝试 2 次或更多）
• 每次修复都会在其他地方暴露出新问题

如果 3 次或更多修复均失败： 质疑架构。

当人类搭档提醒你时（“这不是没发生吗？”，“别猜了”，“我们卡住了吗？”）：返回阶段 1。完整信号列表，以及针对上述每种合理化说辞的借口与现实对照表：./references/rationalizations-and-guardrails.md。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、复现问题、检查改动、收集证据	理解问题是什么以及为什么
2. 模式	查找可正常工作的示例并进行比较	找出差异
3. 假设	提出理论，进行最小化测试	确认假设或提出新假设
4. 实施	编写测试、修复问题、验证	Bug 已解决，测试通过

调查未能找到根本原因时

如果系统性调查表明问题由环境、时序或外部因素导致，则流程已完成——记录调查内容，实施适当的处理方式（重试、超时、错误消息），并添加监控／日志记录以便后续调查。注意： 95% 的“未找到根本原因”案例都意味着调查不完整。

参考资料

• ./references/root-cause-tracing.md - 向后追踪、多层插桩示例
• ./references/rationalizations-and-guardrails.md - 借口对照表、搭档信号、行内计划说明、影响数据
• ./references/defense-in-depth.md - 找到根本原因后，在多个层级添加验证
• ./references/condition-based-waiting.md - 用条件轮询替代任意超时（示例：condition-based-waiting-example.ts）
• ./find-polluter.sh - 对测试套件进行二分查找，以确定哪个测试污染了共享状态
• ../../skills/references/goal-wrapper.md - /goal 语义和条件表述（共享）

相关技能：

• superpowers:behavior-driven-development - BDD 原则，包括用于测试设计的 Gherkin 场景