name: 系统化调试 description: 当遇到任何bug、测试失败或意外行为时使用，在提出修复前

系统化调试

概述

随机修复浪费时间并引入新bug。快速补丁掩盖了根本问题。

核心原则： 在尝试修复前，必须找到根本原因。症状修复是失败的。

违反此流程的字面意义就是违反调试的精神。

铁律

未经根本原因调查，不得提出修复

如果未完成阶段1，就不能提出修复。

何时使用

适用于任何技术问题：

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

尤其在下述情况下使用：

时间紧迫时（紧急情况下容易猜测）
“只是一个快速修复”似乎很明显时
已尝试多种修复时
先前修复无效时
不完全理解问题时

不要跳过的情况：

问题看似简单时（简单bug也有根本原因）
匆忙时（匆忙保证返工）
经理要求立即修复时（系统化比乱试更快）

四个阶段

必须完成每个阶段后才能进入下一阶段。

阶段1：根本原因调查

在尝试任何修复前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们常包含确切解决方案
- 完全阅读堆栈跟踪
- 注意行号、文件路径、错误代码
一致地重现问题
- 能可靠触发吗？
- 确切步骤是什么？
- 每次都发生吗？
- 如果不可重现 → 收集更多数据，不要猜测
检查最近更改
- 哪些更改可能导致此问题？
- Git diff、最近提交
- 新依赖、配置更改
- 环境差异

在多组件系统中收集证据

当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

在提出修复前，添加诊断工具：

对于每个组件边界：
  - 记录进入组件的数据
  - 记录退出组件的数据
  - 验证环境/配置传播
  - 检查每一层的状态

运行一次以收集证据显示哪里出问题
然后分析证据以识别失败组件
然后调查该特定组件

示例（多层系统）：

# 层1：工作流
echo "=== 工作流中的密钥可用性： ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

# 层2：构建脚本
echo "=== 构建脚本中的环境变量： ==="
env | grep IDENTITY || echo "IDENTITY 不在环境中"

# 层3：签名脚本
echo "=== 钥匙串状态： ==="
security list-keychains
security find-identity -v

# 层4：实际签名
codesign --sign "$IDENTITY" --verbose=4 "$APP"

这揭示： 哪一层失败（密钥 → 工作流 ✓，工作流 → 构建 ✗）

追踪数据流

当错误在调用栈深处时：

参见此目录中的 root-cause-tracing.md 获取完整反向追踪技术。

快速版本：
- 错误值源自哪里？
- 什么调用导致此错误值？
- 持续向上追踪直到找到源头
- 在源头修复，不在症状处

阶段2：模式分析

在修复前找到模式：

找到工作示例
- 定位相同代码库中的类似工作代码
- 哪些与损坏的类似并工作？
对照参考进行比较
- 如果实现模式，完整阅读参考实现
- 不要略读——阅读每一行
- 在应用前完全理解模式
识别差异
- 工作与损坏之间有何不同？
- 列出每个差异，无论多小
- 不要假设“那不重要”
理解依赖
- 这需要哪些其他组件？
- 需要什么设置、配置、环境？
- 它做什么假设？

阶段3：假设和测试

科学方法：

形成单一假设
- 清晰陈述：“我认为X是根本原因，因为Y”
- 写下来
- 具体，不模糊
最小化测试
- 做最小的可能更改以测试假设
- 一次一个变量
- 不要同时修复多个问题
在继续前验证
- 是否有效？是 → 阶段4
- 无效？形成新假设
- 不要在基础上添加更多修复
当你不知道时
- 说“我不理解X”
- 不要假装知道
- 寻求帮助
- 更多研究

阶段4：实施

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

创建失败测试用例
- 最简单的可能重现
- 如果可能，自动化测试
- 如果没有框架，一次性测试脚本
- 必须在修复前拥有
- 使用 superpowers:test-driven-development 技能编写适当的失败测试
实施单一修复
- 解决识别的根本原因
- 一次一个更改
- 没有“趁此机会”的改进
- 没有捆绑重构
验证修复
- 测试现在通过吗？
- 没有其他测试损坏？
- 问题实际解决了吗？
如果修复无效
- 停止
- 计数：尝试了多少修复？
- 如果 < 3：返回阶段1，用新信息重新分析
- 如果 ≥ 3：停止并质疑架构（步骤5）
- 未经架构讨论，不要尝试修复#4
如果3+修复失败：质疑架构

指示架构问题的模式：
- 每个修复揭示新的共享状态/耦合/不同地方的问题
- 修复需要“大规模重构”来实施
- 每个修复在其他地方创建新症状
停止并质疑基本原理：
- 此模式根本健全吗？
- 我们是否“仅凭惯性坚持”？
- 我们应该重构架构 vs. 继续修复症状吗？
在尝试更多修复前与人类伙伴讨论

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

红旗 - 停止并遵循流程

如果你发现自己想：

“现在快速修复，稍后调查”
“只是改变X看是否有效”
“添加多个更改，运行测试”
“跳过测试，我会手动验证”
“可能X有问题，让我修复它”
“我不完全理解，但这可能有效”
“模式说X，但我会不同适应它”
“这里主要问题：[未调查就列出修复]”
在追踪数据流前提出解决方案
“再来一次修复尝试”（当已尝试2+时）
每个修复揭示不同地方的新问题

所有这些都意味着：停止。返回阶段1。

如果3+修复失败： 质疑架构（见阶段4.5）

人类伙伴的信号你做得不对

注意这些重定向：

“那没发生吗？” - 你假设而未验证
“它会显示我们…吗？” - 你应该添加证据收集
“停止猜测” - 你在不理解情况下提出修复
“超思考这个” - 质疑基本原理，不仅是症状
“我们卡住了？”（沮丧） - 你的方法无效

当你看到这些： 停止。返回阶段1。

常见合理化

借口	现实
“问题简单，不需要流程”	简单问题也有根本原因。流程对简单bug很快。
“紧急，没时间进行流程”	系统化调试比猜测和检查的乱试更快。
“先试试这个，然后调查”	第一次修复设定模式。从一开始就做对。
“确认修复有效后写测试”	未测试的修复不持久。先测试证明它。
“一次多个修复节省时间”	无法隔离什么有效。导致新bug。
“参考太长，我会适应模式”	部分理解保证bug。完整阅读它。
“我看到问题了，让我修复它”	看到症状 ≠ 理解根本原因。
“再来一次修复尝试”（在2+失败后）	3+失败 = 架构问题。质疑模式，不要再次修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误、重现、检查更改、收集证据	理解什么和为什么
2. 模式	找到工作示例、比较	识别差异
3. 假设	形成理论、最小化测试	确认或新假设
4. 实施	创建测试、修复、验证	bug解决、测试通过

当流程揭示“无根本原因”时

如果系统化调查揭示问题是真正环境性、时间依赖性或外部性：

你已完成流程
记录你调查的内容
实施适当处理（重试、超时、错误消息）
为未来调查添加监控/日志记录

但： 95%的“无根本原因”案例是调查不完整。

支持技术

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

root-cause-tracing.md - 通过调用栈向后追踪bug以找到原始触发
defense-in-depth.md - 找到根本原因后在多个层添加验证
condition-based-waiting.md - 用条件轮询替换任意超时

相关技能：

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

真实世界影响

来自调试会话：

系统化方法：15-30分钟修复
随机修复方法：2-3小时乱试
首次修复率：95% vs 40%
引入新bug：接近零 vs 常见