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

系统化调试

概述

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

核心原则: 在尝试修复之前，始终找到根本原因。症状修复是失败。

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

铁律

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

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

何时使用

适用于任何技术问题：

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

特别在以下情况下使用：

时间压力下（紧急情况容易导致猜测）
“仅一个快速修复”看似明显
已经尝试了多个修复
之前的修复无效
不完全理解问题

不要跳过当：

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

四个阶段

必须在进行下一阶段之前完成每个阶段。

第1阶段：根本原因调查

在尝试任何修复之前：

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

在多组件系统中收集证据

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

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

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

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

示例（多层系统）：

# 第1层：工作流
echo "=== 工作流中可用的密钥： ==="
echo "IDENTITY: ${IDENTITY:+设置}${IDENTITY:-未设置}"

# 第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+次修复失败：质疑架构

指示架构问题的模式：
- 每个修复揭示新的共享状态/耦合/不同地方的问题
- 修复需要“大规模重构”来实现
- 每个修复在其他地方创建新症状
停止并质疑基础：
- 这个模式根本正确吗？
- 我们是否“通过纯粹惯性坚持下去”？
- 我们应该重构架构还是继续修复症状？
在尝试更多修复前与你的人类伙伴讨论

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

红旗 - 停止并遵循流程

如果你发现自己思考：

“现在快速修复，稍后调查”
“只试试改变 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 常见