superpowers-zh 系统化调试技能实战：四阶段根因驱动方法论与配套辅助技术全解

• AI 技能
• AI 插件
• 人工智能
• 开发工具

导读

本文完整讲解开源仓库 superpowers-zh 中 systematic-debugging 技能 的核心方法论：一套面向 AI 编程助手与人类工程师的四阶段调试流程——根因调查 → 模式分析 → 假设与验证 → 实施。文章将以该技能文档为骨架，结合仓库内配套的根因追踪、纵深防御、条件等待三份辅助技术文档及其可运行的示例代码、二分查找脚本与压力测试用例，深入剖析"先找根因、再谈修复"的工程原则。读完本文，你将掌握一套可立即复用的系统化调试 SOP，能在生产故障、不稳定测试、深层调用栈 bug 等场景中脱离"猜改循环"，稳定定位真正的源头。

技能定位与核心原则

技能元信息

该技能以标准 frontmatter 声明元数据（见 SKILL.md）：

name: systematic-debugging description: 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行 version: "1.0.0" license: MIT metadata: hermes: tags: [debugging]

• 触发条件：遇到任何 bug、测试失败或异常行为时，在提出修复方案之前执行；
• 适用范围：既服务于 Claude Code / Copilot CLI / Hermes Agent 等 AI 编程工具（通过 hermes tags 暴露），也是供人类工程师对照执行的标准流程。

核心原则：只修症状就是失败

技能的出发点是两条近乎严苛的约束：

核心原则：在尝试修复之前，务必先找到根本原因。只修症状就是失败。

敷衍走流程等于违背调试的精神。

并有一条"铁律"贯穿始终：

不做根因调查，不许提修复方案

在完成第一阶段（根因调查）之前，不允许提出任何修复方案。这套设计刻意用"ALWAYS / NEVER"式的绝对措辞（而不是"应该/尽量"）来抵抗压力环境下的合理化倾向，这一点在技能的 CREATION-LOG.md 中被明确记录为"bulletproofing"（防弹化）手段——它来自对真实工程中"时间紧迫时最容易猜测式修复"这一观察的系统性反制。

何时使用：覆盖全类型技术问题

技能的"何时使用"部分定义了适用范围，任何技术问题都应触发该流程：

• 测试失败
• 生产环境 bug
• 异常行为
• 性能问题
• 构建失败
• 集成问题

其中有三类高风险情形尤其必须使用：

• 时间紧迫（紧急情况最容易让人猜测式修复）；
• 觉得"一个小修改"就能搞定；
• 已经尝试了多种修复、上一次修复没有生效、或你完全没有理解问题。

同时，技能特别强调以下场景也不要跳过流程：

• 问题看起来很简单——简单的 bug 也有根本原因，只是流程走得更快；
• 你很赶时间——越急越容易返工；
• 领导要求立刻修好——系统化调试比反复尝试更快。

这份"越简单越要查根因、越紧急越要按流程"的设计，正是针对日常工程中两个最大的诱因：轻敌与焦虑。

四个阶段详解：完整调试 SOP

技能要求必须按顺序完成每个阶段，才能进入下一个阶段。下面结合仓库配套文档逐阶段展开。

第一阶段：根因调查（在尝试任何修复之前）

本阶段唯一目标：理解问题，而不是解决问题。四个步骤缺一不可。

1. 仔细阅读错误信息。不要跳过错误或警告——它们往往直接包含解决方案。要求完整阅读堆栈跟踪，并记下行号、文件路径、错误码。

2. 稳定复现。自问：能可靠地触发它吗？具体的复现步骤是什么？每次都能复现吗？如果无法复现，则收集更多数据，而不是猜测。这一步是后续一切验证工作的地基。

3. 检查近期变更。什么变更可能导致了这个问题？重点检查git diff、最近的提交、新依赖、配置变更和环境差异。

4. 在多组件系统中收集证据。当系统有多个组件（如 CI → 构建 → 签名，或 API → 服务 → 数据库）时，在提出修复方案之前先添加诊断埋点，按如下套路执行：

对每个组件边界： - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 执行一次以收集证据，确定断裂点在哪里 然后分析证据，定位故障组件 然后针对该组件深入调查

SKILL.md 给出了一个四层签名链路的诊断示例（工作流 → 构建脚本 → 签名脚本 → 实际签名）：

# 第 1 层：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 第 2 层：构建脚本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # 第 3 层：签名脚本 echo "=== Keychain state: ===" security list-keychains security find-identity -v # 第 4 层：实际签名 codesign --sign "$IDENTITY" --verbose=4 "$APP"

由此可以逐层定位断裂点（例如secrets → workflow ✓, workflow → build ✗），从而锁定故障组件。

5. 跟踪数据流。当错误发生在调用栈深处时，使用完整的反向追踪技术——技能指向 root-cause-tracing.md（详见下文"辅助技术"章节）。简要版三步走：

• 错误值从哪里产生的？
• 谁用错误值调用了这里？
• 持续向上追踪直到找到源头，在源头修复，而不是在症状处修复。

第二阶段：模式分析（先找到模式，再修复）

在确认根因方向后，不要急于下手，先做对照分析：

1. 找到可正常工作的示例——在同一代码库中寻找类似的正常代码，与出问题的代码作对比；
2. 与参考实现对比——如果是实现某个模式，完整阅读参考实现，不要略读，要逐行阅读，在应用之前彻底理解该模式；
3. 识别差异——列出正常代码与出问题代码之间的每一个差异，无论多小；不要假设"那不可能有影响"；
4. 理解依赖关系——这个功能需要哪些其他组件？需要哪些设置、配置、环境？它有哪些隐含假设？

这一阶段直接对治两类常见错误：一知半解照搬模式，以及忽略隐含前提导致"环境性失败"。

第三阶段：假设与验证（科学方法）

采用严格的科学方法循环：

1. 提出单一假设——清晰地陈述："我认为 X 是根本原因，因为 Y"，写下来，要具体不要含糊；
2. 最小化测试——做出最小的改动来验证假设，每次只改一个变量，不要同时修复多个问题；
3. 继续之前先验证——生效了进入第四阶段；没生效则提出新假设，不要在失败假设上叠加更多修复；
4. 当你不确定时——直接说"我不理解 X"，不要假装自己知道，寻求帮助并做更多调研。

"单一假设 + 单变量验证"的设计，是为了强制思考、防止散弹枪式修复（shotgun fixes），这是技能防弹化设计的结构性防御之一（见 CREATION-LOG.md）。

第四阶段：实施（修复根本原因，而非症状）

1. 创建失败的测试用例。先做最简化的复现，尽可能用自动化测试；没有测试框架就写一次性测试脚本。修复前必须先有测试，并建议使用仓库中的 test-driven-development 技能 来编写规范的失败测试。注意技能在 CREATION-LOG 中特别澄清：TDD 的"最简单的代码"原则与调试的"找根因"原则是两套方法论，不要混淆（见 CREATION-LOG.md）。

2. 实施单一修复。只修复已定位的根本原因，每次只改一处；不做"顺便改改"的优化，不捆绑重构。

3. 验证修复。测试通过了吗？其他测试没有被破坏吧？问题真的解决了吗？在宣称成功之前，使用 verification-before-completion 技能 做完成前验证。

4. 如果修复不起作用——止损规则：

• 停下来，先数一数已经尝试了几次修复；
• 少于 3 次：回到第一阶段，用新信息重新分析；
• 3 次或以上：停下来质疑架构（见第 5 步）；
• 没有经过架构讨论，不要尝试第 4 次修复。

5. 如果 3 次以上修复都失败了：质疑架构。以下模式表明存在架构问题：

• 每次修复都暴露出新的共享状态/耦合/其他位置的问题；
• 修复需要"大规模重构"才能实现；
• 每次修复都在其他地方产生新的症状。

此时应停下追问根本性问题：这个模式从根本上合理吗？我们是不是在"惯性驱动"下坚持了错误方案？应该重构架构还是继续修补症状？在尝试更多修复之前，和你的搭档讨论。技能明确：这不是假设失败——这是架构有误。

红线：停下来，按流程走

技能列出了一句式自检清单，一旦发现自己正在想以下任何一句，就必须停下并回到第一阶段：

• "先临时修一下，以后再排查"
• "试着改改 X 看看行不行"
• "一次性改多个地方，跑测试看看"
• "跳过测试，我手动验证"
• "大概是 X 的问题，让我修一下"
• "我不完全理解，但这应该能行"
• "模式说的是 X，但我换个方式用"
• "主要问题有这些：[未经调查就列出修复方案]"
• 没有追踪数据流就提出解决方案
• "再试一次修复"（已经尝试了 2 次以上）
• 每次修复都暴露出不同地方的新问题

红线部分是技能防弹化的核心——它把"当下感觉完全合理"的偷懒瞬间逐字列出，制造认知摩擦（cognitive friction），让使用者看见即止损（见 CREATION-LOG.md）。

搭档发出的信号：说明你的方法不对

在结对调试（或人与 AI 搭档协作）中，同伴的提醒往往是流程偏离的早期警报：

看到这些信号时：停下来，回到第一阶段。

常见借口与对应现实

技能以表格形式逐条驳斥了调试中最常见的合理化借口：

四阶段速查表

当流程显示"找不到根因"时

如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的，则：

1. 你已经完成了流程；
2. 记录你排查了什么；
3. 实施适当的处理措施（重试、超时、错误提示）；
4. 添加监控/日志以便后续排查。

但技能给出了一个清醒的警告：95% 的"找不到根因"其实是排查不充分。换句话说，先怀疑自己的调查深度，再归因于外部环境。

配套辅助技术（同一目录下的深度资料）

系统化调试不是一个孤立的 SKILL，仓库在 skills/systematic-debugging/ 目录下配套了三份可单独引用的技术文档与一份可运行示例，分别是：根因追踪、纵深防御校验、基于条件的等待。下面逐一展开。

根因追踪（root-cause-tracing）

root-cause-tracing.md 解决"Bug 出现在调用栈深处"的典型困境（如git init在错误目录执行、在错误位置创建文件、用错误路径打开数据库）。其核心原则：沿着调用链反向追踪，直到找到最初的触发点，然后在源头修复，并配有决策流程图。

适用场景：错误发生在执行深处（不在入口点）；堆栈跟踪显示很长的调用链；不清楚无效数据从哪里来；需要找出是哪个测试/代码触发了问题。

追踪流程以一个真实的 TypeScript 案例完整演示：

1. 观察症状：Error: git init failed in /Users/jesse/project/packages/core；
2. 找到直接原因：await execFileAsync('git', ['init'], { cwd: projectDir })；
3. 问：谁调用了它？沿调用链上溯WorktreeManager.createSessionWorktree(projectDir, sessionId) → Session.initializeWorkspace() → Session.create() → 测试中的 Project.create()；
4. 继续向上追踪：发现传入的projectDir = ''（空字符串！），空字符串作为cwd会被解析为process.cwd()——即源代码目录；
5. 找到最初的触发点：setupCoreTest()初始返回{ tempDir: '' }，而测试在beforeEach之前就访问了它。

添加堆栈跟踪：当无法手动追踪时，在危险操作之前注入诊断埋点，用new Error().stack捕获完整调用链，并记录directory、cwd、process.env.NODE_ENV等上下文：

// 在有问题的操作之前 async function gitInit(directory: string) { const stack = new Error().stack; console.error('DEBUG git init:', { directory, cwd: process.cwd(), nodeEnv: process.env.NODE_ENV, stack, }); await execFileAsync('git', ['init'], { cwd: directory }); }

两个关键技巧：在测试中使用console.error()而非 logger（logger 可能被抑制、不会显示）；运行时用npm test 2>&1 | grep 'DEBUG git init'捕获输出。分析堆栈跟踪时：找测试文件名、找触发调用的行号、识别模式（同一个测试？同一个参数？）。

找出导致污染的测试：当测试期间出现诡异状态但不知道是谁造成时，使用同目录下的二分查找脚本 find-polluter.sh：

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

该脚本逐个运行匹配的测试文件，在第一个"污染者"（即创建了目标文件/目录的测试）处停止并输出定位信息。脚本内部做了两处健壮性处理：去除./前缀以兼容两种写法，以及将**/折叠一次以匹配直接位于基础目录下的文件（见 find-polluter.sh 注释）。

真实案例的最终复盘：空 projectDir 事件的五层追踪链、根因（顶层变量初始化时访问了空值）、修复（把tempDir改为 getter，在beforeEach之前访问时抛出异常），以及同时添加的四层纵深防御（详见下文）。文档给出实际效果：5 层追踪找到根因、源头修复、4 层防御、1847 个测试通过且零污染（见 root-cause-tracing.md）。

纵深防御校验（defense-in-depth）

defense-in-depth.md 回答一个问题：找到根因、修完 bug 之后呢？单点校验可能被不同的代码路径、重构或 mock 绕过，因此核心原则是：在数据经过的每一层都做校验，让这个 bug 在结构上不可能发生。

单层校验的语义是"我们修了这个 bug"，多层校验的语义是"我们让这个 bug 不可能再发生"。文档给出四个层级，各有分工：

第 1 层：入口校验——在 API 边界拒绝明显无效的输入：

function createProject(name: string, workingDirectory: string) { if (!workingDirectory || workingDirectory.trim() === '') { throw new Error('workingDirectory cannot be empty'); } if (!existsSync(workingDirectory)) { throw new Error(`workingDirectory does not exist: ${workingDirectory}`); } if (!statSync(workingDirectory).isDirectory()) { throw new Error(`workingDirectory is not a directory: ${workingDirectory}`); } // ... 继续处理 }

第 2 层：业务逻辑校验——确保数据对当前操作是合理的（如工作区初始化要求projectDir非空）。

第 3 层：环境守卫——防止在特定环境中执行危险操作。示例为测试环境下拒绝在临时目录之外执行git init：

async function gitInit(directory: string) { // 在测试中，拒绝在临时目录之外执行 git init if (process.env.NODE_ENV === 'test') { const normalized = normalize(resolve(directory)); const tmpDir = normalize(resolve(tmpdir())); if (!normalized.startsWith(tmpDir)) { throw new Error( `Refusing git init outside temp dir during tests: ${directory}` ); } } // ... 继续处理 }

第 4 层：调试埋点——记录目录、cwd、堆栈等上下文信息，供其他层级失效时事后分析。

应用模式：发现 bug 后，先追踪数据流（错误值从哪里产生、在哪里被使用），再标注所有检查点（数据经过的每一个节点），然后在每一层添加校验，最后逐层测试（尝试绕过第 1 层，验证第 2 层能否捕获）。

文档用空 projectDir 案例说明了四层防御的实际落点：Project.create()校验非空/存在/可写 →WorkspaceManager校验 projectDir 非空 →WorktreeManager在测试中拒绝在 tmpdir 之外执行 git init → git init 前记录堆栈跟踪。关键洞察是四层缺一不可：不同代码路径绕过入口校验、mock 绕过业务逻辑检查、跨平台边界情况需要环境守卫、调试日志发现结构性误用——每一层都捕获过其他层遗漏的 bug（见 defense-in-depth.md）。

基于条件的等待（condition-based-waiting）

condition-based-waiting.md 专门对付不稳定测试：硬编码延迟（setTimeout、sleep）本质是在猜测时序，会造成竞态条件——在快速机器上通过，在高负载或 CI 环境下失败。核心原则：等待你真正关心的条件，而不是猜测它需要多长时间。

适用场景：测试中有硬编码延迟；测试不稳定（时而通过，高负载下失败）；并行运行时测试超时；等待异步操作完成。不适用场景：测试实际的时序行为（如防抖、节流间隔）；此时若必须用硬编码超时，务必注释说明原因。

核心模式对照：

// ❌ 之前：猜测时序 await new Promise(r => setTimeout(r, 50)); const result = getResult(); expect(result).toBeDefined(); // ✅ 之后：等待条件满足 await waitFor(() => getResult() !== undefined); const result = getResult(); expect(result).toBeDefined();

常用模式速查：

通用轮询函数实现：带超时保护的 10ms 轮询，超时即抛出带清晰描述的错误：

async function waitFor<T>( condition: () => T | undefined | null | false, description: string, timeoutMs = 5000 ): Promise<T> { const startTime = Date.now(); while (true) { const result = condition(); if (result) return result; if (Date.now() - startTime > timeoutMs) { throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`); } await new Promise(r => setTimeout(r, 10)); // 每 10ms 轮询一次 } }

三个常见错误与修正：轮询太频繁（setTimeout(check, 1)浪费 CPU，改为每 10ms 一次）；没有超时（条件永远不满足时无限循环，必须始终设置超时并提供清晰错误信息）；数据过期（在循环外缓存状态，应在循环内调用 getter 获取最新数据）。

何时硬编码超时才是正确的：先等待触发条件，再基于已知时序（而非猜测）等待，并注释说明原因。文档示例：工具每 100ms tick 一次，需要 2 次 tick 验证部分输出，则先waitForEvent(manager, 'TOOL_STARTED')，再setTimeout(200ms)并注释// 200ms = 100ms 间隔的 2 次 tick——有文档说明且有充分理由。

完整实现与领域专用辅助函数：同目录下的 condition-based-waiting-example.ts 提供了源自真实调试过程（Lace 测试基础设施改进）的完整可运行实现，包含三个带类型定义的领域专用函数：

• waitForEvent(threadManager, threadId, eventType, timeoutMs = 5000)——等待指定事件类型首次出现；
• waitForEventCount(threadManager, threadId, eventType, count, timeoutMs = 5000)——等待指定数量的事件（如等待 2 次AGENT_MESSAGE：初始回复 + 后续延续），超时错误中会报告实际收到数量；
• waitForEventMatch(threadManager, threadId, predicate, description, timeoutMs = 5000)——按自定义谓词匹配事件数据，而非仅匹配类型（如等待TOOL_RESULT且e.data.id === 'call_123'）。

文件末尾附带了修复前后对比的真实用例：修复前靠setTimeout(300)+setTimeout(50)猜测工具启动与结果到达的时序，导致expect(toolResults.length).toBe(2)随机失败；修复后改用waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2)等待工具启动、waitForEventCount(..., 'TOOL_RESULT', 2)等待结果，断言稳定通过。文档记录的实际效果：修复了 3 个文件中的 15 个不稳定测试，通过率 60% → 100%，执行时间快了 40%，再无竞态条件（见 condition-based-waiting.md）。

技能的诞生与验证：从实战中提炼并经受压力测试

理解这套方法论如何被"打磨成防弹形态"，能帮助读者更正确地使用它。CREATION-LOG.md 记录了技能的来源：从一份真实工程环境中的CLAUDE.md调试框架中提取、按技能创作规范结构化，并通过三重手段防弹化：

• 语言选择：用"ALWAYS / NEVER"取代"应该/尽量"，用"即使看起来更快/即使我似乎很赶时间"等措辞封堵压力场景的合理化出口；
• 结构防御：第一阶段强制前置、单一假设规则、显式失败模式（第一次修复失败后的强制动作）、反模式清单；
• 冗余强化：根因命令在概述、使用时机、第一阶段与实施规则中反复出现，"绝不修症状"在不同语境出现 4 次。

该技能配套了 4 份验证测试（位于同一目录），分别覆盖不同压力场景：

• test-academic.md：无压力学术场景，验证对四阶段流程的完整理解与引用准确性；
• test-pressure-1.md：生产故障紧急场景——API 宕机每分钟损失 1.5 万美元、管理者施压、快速修复看起来只需 5 分钟，考察是否抵抗捷径；
• test-pressure-2.md：沉没成本 + 疲惫场景——已花 4 小时猜改超时仍不稳定，考察能否放弃"再试一次"回到第一阶段；
• test-pressure-3.md：权威与社会压力场景——资深工程师与技术主管都主张直接修复，考察是否坚持先查根因。

CREATION-LOG 记录了四份测试的结果：全部通过，未发现合理化行为——包括在"明显快速修复"诱惑下仍坚持完整流程并找到真正根因、在多层系统失败中逐层追踪到源头、在首次假设失败后停下重新分析而非散弹枪式叠加（见 CREATION-LOG.md）。这些测试文件本身即可作为团队演练系统化调试的现成素材。

实战落地建议

1. 把"铁律"挂在工作区可见处：不做根因调查，不许提修复方案——对 AI 编程助手与结对搭档同样生效；
2. 遇到不稳定测试，先替换硬编码等待：直接复用 condition-based-waiting-example.ts 中的waitForEvent*模式改造现有断言；
3. 深层调用栈错误，先反向追踪再动手：参考 root-cause-tracing.md 的五步追踪流程与new Error().stack埋点技巧，必要时用 find-polluter.sh 定位污染测试；
4. 修复完成后不要止步：按 defense-in-depth.md 在入口、业务逻辑、环境、调试四个层级补上校验，让 bug"结构上不可能再发生"；
5. 守住止损线：第 2 次修复失败就停止叠加，第 3 次失败直接质疑架构——这是该技能最反直觉、也最省时间的一条规则。

• AI 技能
• AI 插件
• 人工智能
• 开发工具