名称: 系统性调试描述: 在遇到任何bug、测试失败或意外行为时使用，在提出修复之前 - 四阶段框架（根本原因调查、模式分析、假设测试、实施），确保在尝试解决方案前理解问题

系统性调试

概述

随机修复浪费时间并创建新bug。快速补丁掩盖潜在问题。

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

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

铁律

没有根本原因调查，就没有修复

何时使用

用于任何技术问题：

测试失败
生产中的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"

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

追踪数据流

当错误在调用栈深处时：

必需子技能： 使用超能力:根因追踪进行反向追踪技术

快速版本：
- 坏值起源于哪里？
- 什么用坏值调用了这个？
- 一直追踪直到找到来源
- 在源头修复，不在症状处

阶段 2: 模式分析

在修复之前找到模式：

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

阶段 3: 假设和测试

科学方法：

形成单一假设
- 清晰陈述：“我认为 X 是根本原因，因为 Y”
- 写下来
- 具体，不模糊
最小化测试
- 做尽可能小的改变来测试假设
- 一次一个变量
- 不要一次修复多个东西
在继续前验证
- 它工作了吗？是 → 阶段 4
- 没工作？形成新假设
- 不要在此基础上添加更多修复
当你不懂时
- 说“我不理解 X”
- 不要假装懂
- 寻求帮助
- 研究更多

阶段 4: 实施

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

创建失败测试案例
- 最简单的可能复现
- 自动化测试如果可能
- 如果没框架，一次性测试脚本
- 必须在修复前有
- 必需子技能： 使用超能力:测试驱动开发编写适当的失败测试
实施单一修复
- 处理识别的根本原因
- 一次一个改变
- 没有“趁我在这里”的改进
- 没有捆绑重构
验证修复
- 现在测试通过了吗？
- 没有其他测试损坏？
- 问题实际解决了吗？
如果修复不工作
- 停止
- 计数：你尝试了多少修复？
- 如果 < 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% 的“没有根本原因”案例是不完全调查。

与其他技能集成

此技能需要使用：

根因追踪 - 必需当错误在调用栈深处时（见阶段 1，步骤 5）
测试驱动开发 - 必需创建失败测试案例时（见阶段 4，步骤 1）

补充技能：

深度防御 - 在找到根本原因后添加多层验证
基于条件的等待 - 替换在阶段 2 识别的任意超时
完成前验证 - 在声称成功前验证修复工作

现实世界影响

来自调试会话：

系统性方法：15-30 分钟修复
随机修复方法：2-3 小时瞎忙
首次修复率：95% vs 40%
引入新bug：几乎为零 vs 常见

名称: 系统性调试 描述: 在遇到任何bug、测试失败或意外行为时使用，在提出修复之前 - 四阶段框架（根本原因调查、模式分析、假设测试、实施），确保在尝试解决方案前理解问题