名称: 系统化调试描述: 在遇到任何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阶段：实现

修复根因，不是症状：

创建失败测试用例
- 最简单可能的重现
- 如果可能，自动化测试
- 如果没有框架，一次性测试脚本
- 必须在修复前有
- 使用.claude/skills/test-driven-development/SKILL.md技能编写适当的失败测试
实现单一修复
- 解决识别的根因
- 一次一个更改
- 没有“既然我在这里”的改进
- 没有捆绑重构
验证修复
- 测试现在通过吗？
- 没有其他测试被破坏？
- 问题实际解决了吗？
如果修复不起作用
- 停止
- 计数：你尝试了多少修复？
- 如果< 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常见

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