version: "1.0.0" name: systematic-debugging description: 在遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用

系统化调试

概述

随机修复会浪费时间并引入新 bug。快速修补只会掩盖潜在问题。

核心原则： 永远要先找到根本原因，再尝试修复。只修复症状就是失败。

违反这一流程的字面要求，就是违反调试的精神。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果你还没有完成第一阶段，就不能提出修复方案。

何时使用

用于任何技术问题：

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

尤其在以下情况使用：

• 时间紧迫时（紧急情况容易让人想猜测）
• “只改一个小地方”看起来很显然
• 你已经尝试了多种修复
• 上一个修复没有奏效
• 你并没有完全理解问题

不要跳过：

• 问题看起来简单（简单 bug 也有根本原因）
• 你很匆忙（匆忙必然导致返工）
• 经理要求立刻修复（系统化比盲目尝试更快）

四个阶段

你必须按顺序完成每个阶段，才能进入下一阶段。

第一阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

• 不要跳过错误或警告
• 它们通常包含确切的解决方案
• 完整阅读堆栈跟踪
• 记录行号、文件路径、错误代码

1. 稳定复现

• 你能否可靠地触发它？
• 具体步骤是什么？
• 每次都会发生吗？
• 如果不能复现 → 收集更多数据，不要猜测

1. 检查最近变更

• 有什么变更可能导致这个问题？
• Git diff、最近提交
• 新依赖、配置变更
• 环境差异

1. 在多组件系统中收集证据

当系统包含多个组件时（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 ```

示例（多层系统）： ```bash # 第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" ```

这会揭示： 哪一层出现故障（密钥 → 工作流 ✓，工作流 → 构建 ✗）

1. 追踪数据流

当错误出现在调用栈深处时：

请参阅本目录中的 project-cause-tracing.md，了解完整的反向追踪技术。

快速版本：

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

第二阶段：模式分析

在修复之前找到模式：

1. 寻找正常工作的示例

• 在同一代码库中找到类似的正常代码
• 与损坏代码相似的正常代码是什么？

1. 与参考实现对比

• 如果是在实现某种模式，完整阅读参考实现
• 不要略读——逐行阅读
• 在应用之前充分理解该模式

1. 识别差异

• 正常与损坏之间有什么不同？
• 列出每一个差异，无论多小
• 不要假设“那不可能有影响”

1. 理解依赖

• 这个组件依赖哪些其他组件？
• 需要哪些设置、配置、环境？
• 它做出了哪些假设？

第三阶段：假设与验证

科学方法：

1. 形成单一假设

• 清楚表述：“我认为 X 是根本原因，因为 Y”
• 把它写下来
• 具体，不要模糊

1. 最小化验证

• 做最小的改动来验证假设
• 一次只改变一个变量
• 不要同时修复多个问题

1. 验证后再继续

• 有效？→ 进入第四阶段
• 无效？→ 形成新的假设
• 不要在上面叠加更多修复

1. 当你不知道时

• 说出“我不理解 X”
• 不要假装知道
• 寻求帮助
• 进一步研究

第四阶段：实施

修复根本原因，而不是症状：

1. 创建失败的测试用例

• 最简单的复现
• 如果可能，使用自动化测试
• 如果没有框架，用一次性测试脚本
• 修复前必须有
• 使用 superpowers:test-driven-development 技能来编写正确的失败测试

1. 实施单一修复

• 针对已识别的根本原因
• 一次只做一个改动
• 不要顺手做“顺便改进”
• 不要打包重构

1. 验证修复

• 测试现在通过了吗？
• 其他测试有没有被破坏？
• 问题真的解决了吗？

1. 如果修复无效

• 停下
• 统计：你已经尝试了多少次修复？
• 如果 < 3：回到第一阶段，用新信息重新分析
• 如果 ≥ 3：停下并质疑架构（见下方第 5 步）
• 在没有进行架构讨论之前，不要尝试第 4 次修复

1. 如果 3 次以上修复失败：质疑架构

表明存在架构问题的模式：

• 每次修复都会在不同地方暴露出新的共享状态/耦合/问题
• 修复需要“大规模重构”才能实现
• 每次修复都会在其他地方引发新症状

停下并质疑基本设计：

• 这个模式从根本上讲是否合理？
• 我们是否只是在“凭惯性坚持”？
• 我们应该重构架构，还是继续修复症状？

在尝试更多修复之前，先与人类伙伴讨论

这不是假设失败——这是架构错误。

危险信号——停下并遵循流程

如果你发现自己这样想：

• “先临时修一下，以后再调查”
• “改一下 X 看看有没有用”
• “加多处改动，然后跑测试”
• “跳过测试，我手动验证”
• “很可能是 X，我来修它”
• “我不太懂，但这可能有用”
• “模式要求 X，但我会换一种方式实现”
• “主要问题有这几个：[还没调查就列出修复]”
• 在追踪数据流之前就提出解决方案
• “再试一次修复”（已经失败 2 次以上）
• 每次修复都在不同地方暴露出新问题

以上任何一条都意味着：停下。回到第一阶段。

如果 3 次以上修复失败： 质疑架构（见第四阶段第 5 步）

来自人类伙伴的“你做错了”信号

注意这些引导性反馈：

• “这种情况没有发生吗？”——你在没有验证的情况下做出了假设
• “这会显示给我们……吗？”——你本应该添加证据收集
• “别猜了”——你在没有理解的情况下就提出修复
• “再深入想想”——要质疑根本问题，而不是只看症状
• “我们卡住了吗？”（不耐烦）——你的方法行不通

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

常见借口

快速参考

当流程显示“没有根本原因”

如果系统调查显示问题确实是环境、时机或外部因素导致的：

1. 你已经完成了流程
2. 记录你调查过的内容
3. 实施适当的处理（重试、超时、错误信息）
4. 添加监控/日志以便未来调查

但是： 95% 的“没有根本原因”情况都是调查不完整。

辅助技术

这些技术是系统化调试的一部分，可在本目录中找到：

• `project-cause-tracing.md` - 反向追踪调用栈以找到原始触发点
• `project-defense-in-depth.md` - 找到根本原因后在多个层次添加验证
• `project-condition-based-waiting.md` - 用条件轮询替代任意超时

相关技能：

• superpowers:test-driven-development - 用于创建失败测试用例（第四阶段，第 1 步）
• superpowers:verification-before-completion - 在声称成功之前验证修复是否有效

实际影响

来自调试实践：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时盲目尝试
• 首次修复成功率：95% 对比 40%
• 引入的新 bug：几乎为零 对比 常见