systematic-debugging

系统化调试

概述

核心原则： 在尝试任何修复之前，必须先找到根本原因。治标不治本的修复就是失败。

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

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

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

适用场景

适用于任何技术问题：

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

尤其适用于以下情况：

• 处于时间压力之下（紧急情况下容易想靠猜测解决）
• 觉得"就改一下应该能好"的想法很明显
• 已经尝试过多种修复
• 之前的修复没有生效
• 你并不完全理解问题

以下情况也不能跳过：

• 问题看起来很简单（简单的 Bug 同样有根本原因）
• 你很赶时间（匆忙只会导致返工）
• 经理要求立即修复（系统化方法比反复试错更快）

四个阶段

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

第一阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决线索
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径和错误代码

2. 稳定复现

   • 你能否可靠地触发该问题？
   • 确切的步骤是什么？
   • 每次都会发生吗？
   • 如果无法复现，就收集更多数据，而不是去猜

3. 检查近期变更

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

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: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || 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.md。

   简要版本：

   • 错误的值从哪里产生？
   • 是什么调用方传入了错误的值？
   • 持续向上追溯，直到找到源头
   • 在源头修复，而不是修复症状

第二阶段：模式分析

在修复之前先找出模式：

1. 查找可用的示例

   • 在同一代码库中找到类似的可用代码
   • 哪些与出错的部分相似的代码是正常工作的？

2. 与参考实现对比

   • 如果要实现某个模式，请完整阅读参考实现
   • 不要略读，逐行阅读
   • 在应用模式之前，充分理解它

3. 找出差异

   • 正常工作的代码与出错的代码有何不同？
   • 列出每一处差异，无论多么细微
   • 不要假设"这不可能有影响"

4. 理解依赖关系

   • 这部分还依赖哪些其他组件？
   • 需要哪些设置、配置和环境？
   • 它做了哪些假设？

第三阶段：假设与验证

科学方法：

1. 提出单一假设

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

2. 最小化验证

   • 做出尽可能小的改动来验证假设
   • 每次只改变一个变量
   • 不要同时修复多处

3. 继续前先验证

   • 是否生效？是，则进入第四阶段
   • 未生效？则提出新的假设
   • 不要在此基础上叠加更多修复

4. 当你不了解时

   • 直接说明"我不理解 X"
   • 不要假装懂
   • 寻求帮助
   • 进一步研究

阶段 4：实施

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

1. 创建失败的测试用例

   • 尽可能简单的复现步骤
   • 尽可能自动化
   • 若没有测试框架，则编写一次性测试脚本
   • 修复前必须完成
   • 编写规范的失败测试时，使用 superpowers:test-driven-development 技能

2. 实施单一修复

   • 针对已找出的根本原因
   • 每次只做一处改动
   • 不做“顺便”的改进
   • 不捆绑重构

3. 验证修复

   • 测试现在能通过吗？
   • 是否有其他测试被破坏？
   • 问题是否真正解决？
   • 在宣称成功之前，使用 superpowers:verification-before-completion 技能

4. 如果修复无效

   • 停止
   • 计数：你已经尝试了多少次修复？
   • 如果少于 3 次：返回阶段 1，结合新信息重新分析
   • 如果 ≥ 3 次：停止，并质疑架构（见下方第 5 步）
   • 在进行架构讨论之前，不要尝试第 4 次修复

5. 如果 3 次以上修复失败：质疑架构

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

   • 每次修复都会在别处暴露新的共享状态、耦合或问题
   • 实施修复需要“大规模重构”
   • 每次修复都会在其他地方产生新症状

   停止并质疑根本设计：

   • 这种模式本身是否合理？
   • 我们是否只是出于惯性“硬撑下去”？
   • 应该重构架构，还是继续修补症状？

   在尝试更多修复之前，与你的人类搭档讨论

   这不是假设被证伪，而是架构错误。

危险信号：出现以下情况时停止并遵循流程

如果你发现自己在想：

• “先临时快速修一下，之后再调查”
• “改一下 X 看看行不行”
• “同时加多处改动，跑测试看看”
• “跳过测试，我手动验证就行”
• “大概是 X 的问题，我来改那里”
• “我不完全理解，但这样可能有效”
• “模式说要这样做，但我想换个方式适配”
• “主要问题如下：[未经调查就列出修复方案]”
• 在追踪数据流之前就提出解决方案
• “再试一次修复”（已经尝试过 2 次或以上）
• 每次修复都在别处引出新问题

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

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

你的人类搭档发出的信号：说明你做错了

留意以下提醒：

• “那种情况不会发生吗？”：你没有验证就做了假设
• “这样能看出来吗？”：你本应先收集证据
• “别瞎猜”：你在没有理解问题的情况下提出修复
• “深度思考一下”：应质疑根本问题，而不只是症状
• “我们卡住了？”（带着沮丧）：你的方法行不通

看到这些信号时： 停止，返回阶段 1。

常见的自我合理化

借口	现实
“问题简单，不需要流程”	简单问题同样有根本原因。对于简单的 bug，流程同样很快。
“紧急情况，没时间走流程”	系统化调试比凭猜测反复试错更快。
“先试试这个，之后再调查”	第一次修复会定下模式。从一开始就要做对。
“等确认修复有效后再写测试”	未经测试的修复站不住脚。先写测试才能证明修复有效。
“一次性多处修复能节省时间”	无法分离出真正起作用的改动，还会引入新 bug。
“参考资料太长，我改编一下模式就行”	理解不完整必然导致 bug。应完整阅读。
“我看到问题了，直接改”	看到症状不等于理解了根本原因。
“再试一次修复”（失败 2 次以上之后）	3 次以上失败意味着存在架构问题。应质疑模式，而不是继续修复。

快速参考

阶段	关键活动	成功标准
1. 根本原因	阅读错误信息、复现问题、检查变更、收集证据	理解 WHAT 与 WHY
2. 模式	查找可正常工作的示例并进行比较	找出差异
3. 假设	提出理论，进行最小化验证	确认或提出新假设
4. 实施	创建测试、修复、验证	问题已解决，测试通过

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

如果系统性排查表明问题确实属于环境性、时序相关或外部因素：

1. 你已完成整个过程
2. 记录你所排查的内容
3. 实施适当的处理措施（重试、超时、错误提示）
4. 添加监控/日志，以便后续排查

但是： 95% 的“无根本原因”情况，其实是排查不完整。

辅助技术

以下技术属于系统性调试的一部分，可在本目录中找到：

• root-cause-tracing.md - 沿调用栈反向追踪缺陷，找到原始触发点
• defense-in-depth.md - 在找到根本原因后，于多个层级添加校验
• condition-based-waiting.md - 用条件轮询替代任意超时