debugging

系统化调试

概述

随机修复会浪费时间，还会引入新 Bug。快速打补丁会掩盖根本问题。

核心原则： 尝试修复前，务必先找到根本原因。只修复症状就是失败。

违背此流程的字面要求，就是违背调试的精神。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

适用场景

任何技术问题都适用：

• 测试失败
• 生产环境中的 Bug
• 行为异常
• 性能问题
• 构建失败
• 集成问题

尤其适用于：

• 时间紧迫时（紧急情况会让人忍不住猜测）
• “只要快速修一下”看起来显而易见时
• 已经尝试过多种修复方法时
• 之前的修复无效时
• 尚未完全理解问题时

不要在以下情况下跳过：

• 问题看起来很简单时（简单 Bug 也有根本原因）
• 赶时间时（仓促行事必然导致返工）
• 经理要求立即修复时（系统化处理比反复折腾更快）

四个阶段

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

阶段 1：调查根本原因

尝试任何修复之前：

1. 仔细阅读错误消息

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

2. 稳定复现问题

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

3. 检查近期变更

   • 哪些变更可能导致此问题？
   • Git 差异、近期提交
   • 新增依赖、配置变更
   • 环境差异

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

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

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

   这可以揭示： 哪一层发生故障（机密信息 → 工作流 ✓，工作流 → 构建 ✗）

5. 追踪数据流

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

   请参阅 root-cause-tracing 技能，了解反向追踪技术

   简要步骤：

   • 错误值从何处产生？
   • 哪个调用方传入了错误值？
   • 持续向上追踪，直到找到来源
   • 在来源处修复，而不是修复症状

阶段 2：模式分析

修复前先找出模式：

1. 查找可正常工作的示例

   • 在同一代码库中找到类似的可运行代码
   • 类似代码中，哪些部分能正常工作，而故障代码却不能？

2. 对照参考实现

   • 如果要实现某种模式，请完整阅读参考实现
   • 不要略读——逐行阅读
   • 应用前先全面理解该模式

3. 找出差异

   • 可正常工作的部分与故障部分有何不同？
   • 列出所有差异，无论多细微
   • 不要想当然地认为“这不可能有影响”

4. 理解依赖项

   • 该功能需要哪些其他组件？
   • 需要哪些设置、配置和环境？
   • 它依赖哪些假设？

阶段 3：提出假设并进行测试

采用科学方法：

1. 提出单一假设

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

2. 进行最小化测试

   • 做尽可能小的改动来测试假设
   • 一次只改变一个变量
   • 不要同时修复多个问题

3. 继续之前先验证

   • 是否有效？是 → 进入阶段 4
   • 无效？提出新假设
   • 不要在现有修复之上继续叠加修复

4. 遇到不确定时

   • 直说“我不理解 X”
   • 不要假装懂
   • 寻求帮助
   • 进一步调研

阶段 4：实现

修复根本原因，而非表面症状：

1. 创建失败测试用例

   • 尽可能简单地复现问题
   • 尽可能编写自动化测试
   • 如果没有测试框架，则编写一次性测试脚本
   • 修复前必须先完成

2. 实施单一修复

   • 解决已确定的根本原因
   • 一次只做一项更改
   • 不要顺手做其他改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在通过了吗？
   • 有没有导致其他测试失败？
   • 问题确实解决了吗？

4. 如果修复无效

   • 停止
   • 统计：你尝试过多少种修复？
   • 如果少于 3 种：返回阶段 1，根据新信息重新分析
   • 如果 ≥ 3 种：停止并质疑架构（见下方第 5 步）
   • 未讨论架构前，不要尝试第 4 种修复

5. 如果 3 种或更多修复均失败：质疑架构

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

   • 每次修复都会在其他位置揭示新的共享状态、耦合或问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方引发新症状

   停止并质疑根本问题：

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

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

   这不是假设失败了，而是架构有误。

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

如果你发现自己在想：

• “先快速修一下，之后再调查”
• “先试着改一下 X，看能不能解决”
• “多做几项更改，再运行测试”
• “跳过测试，我手动验证就行”
• “问题可能是 X，我来修一下”
• “我还没完全弄明白，但这样也许行”
• “模式表明应该用 X，但我会换种方式”
• “主要问题有这些：[未调查就列出修复方案]”
• 尚未追踪数据流就提出解决方案
• “再尝试修复一次”（已经尝试过 2 次或更多时）
• 每次修复都会在其他位置暴露新问题

以上任何一种情况都意味着：停止。返回阶段 1。

**如果 3 种或更多修复均失败：**质疑架构（参见阶段 4.5）

常见的自我辩解

借口	实际情况
“问题很简单，不需要走流程”	简单问题也有根本原因。处理简单错误时，流程很快。
“情况紧急，没时间走流程”	系统性调试比反复猜测和尝试更快。
“先试试这个，再调查”	第一次修复会奠定后续模式。从一开始就做好。
“确认修复有效后再写测试”	未经测试的修复难以持续有效。先写测试才能验证。
“一次做多项修复能节省时间”	无法确定哪项修复起了作用，还会引入新错误。
“参考资料太长，我会灵活套用模式”	只理解一部分必然会导致错误。请完整阅读。
“我看出问题了，让我来修”	看到症状 ≠ 理解根本原因。
“再尝试修复一次”（失败 2 次或更多后）	失败 3 次或更多，说明存在架构问题。质疑模式，不要再次修复。

快速参考

阶段	主要活动	成功标准
1. 根本原因	阅读错误信息、复现问题、检查更改、收集证据	理解是什么问题以及原因
2. 模式	查找可用示例、进行比较	找出差异
3. 假设	提出理论、进行最小化测试	得到确认或提出新假设
4. 实现	创建测试、修复、验证	错误已解决，测试通过

流程未发现“根本原因”时

如果系统性调查表明问题确实由环境、时序或外部因素导致：

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

**但是：**95% 的“没有根本原因”情况其实是调查不充分。

与其他技能集成

此技能可与以下技能配合使用：

• root-cause-tracing - 如何沿调用栈向上追溯
• defense-in-depth-validation - 找到根本原因后添加验证

实际影响

根据调试经验：

• 系统化方法：15-30 分钟即可修复
• 随机修复方法：需要 2-3 小时反复折腾
• 一次修复成功率：95% vs 40%
• 引入的新 Bug：几乎为零 vs 很常见