systematic-debugging

name	systematic-debugging
description	遇到任何 bug、测试失败或意外行为时使用，在提出修复之前先进行系统化调查

系统化调试

概述

随机修复浪费时间并制造新 bug。快速补丁掩盖底层问题。

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

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

铁律

没有根因调查，不得进行任何修复

如果你没有完成阶段 1，就不能提出修复方案。

何时使用

用于任何技术问题：

• 测试失败
• 生产环境 bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其在以下情况使用：

• 时间压力下（紧急情况使猜测变得诱人）
• "一个快速修复"看起来很明显
• 你已经尝试了多个修复
• 之前的修复没有奏效
• 你没有完全理解问题

不要跳过，即使：

• 问题看起来很简单（简单的 bug 也有根因）
• 你很急（急躁保证返工）
• 上级要求立刻修好（系统化比乱试更快）

四个阶段

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

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

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

2. 稳定复现

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

3. 检查近期变更

   • 什么变更可能导致了这个？
   • Git diff、近期提交
   • 新依赖、配置变更
   • 环境差异

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

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

   在提出修复之前，添加诊断插桩：

   对每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置的传递
     - 检查每一层的状态
   
   运行一次以收集证据，展示哪里断了
   然后分析证据以识别故障组件
   然后调查那个特定组件
   

   示例（多层系统）：

   # 第 1 层：工作流
   echo "=== 工作流中可用的 Secrets: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # 第 2 层：构建脚本
   echo "=== 构建脚本中的环境变量: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # 第 3 层：签名脚本
   echo "=== Keychain 状态: ==="
   security list-keychains
   security find-identity -v
   
   # 第 4 层：实际签名
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   

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

5. 追踪数据流

   当错误深在调用栈中时：

   参见本目录下的 root-cause-tracing.md 了解完整的反向追踪技术。

   快速版本：

   • 错误值从哪里来的？
   • 谁用错误值调用了这里？
   • 继续向上追踪直到找到源头
   • 在源头修复，而非在症状处

阶段 2：模式分析

在修复之前找到模式：

1. 找到可工作的示例

   • 在同一代码库中找到类似的可工作代码
   • 什么类似的东西是工作的？

2. 对照参考比较

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

3. 识别差异

   • 可工作的和损坏的之间有什么不同？
   • 列出每个差异，无论多小
   • 不要假设"那不可能有影响"

4. 理解依赖

   • 这需要什么其他组件？
   • 什么设置、配置、环境？
   • 它做了什么假设？

阶段 3：假设与测试

科学方法：

1. 形成单一假设

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

2. 最小化测试

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

3. 继续之前验证

   • 有效了吗？是 → 阶段 4
   • 无效？形成新假设
   • 不要在上面叠加更多修复

4. 当你不确定时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 研究更多

阶段 4：实现

修复根因，而非症状：

1. 创建失败的测试用例

   • 最简单的可能复现
   • 如果可能使用自动化测试
   • 如果没有框架则用一次性测试脚本
   • 修复之前必须有
   • 使用 test-driven-development skill 编写正确的失败测试

2. 实现单一修复

   • 解决已识别的根因
   • 每次一个变更
   • 不要"顺便"改进
   • 不要捆绑重构

3. 验证修复

   • 测试现在通过了？
   • 没有其他测试被破坏？
   • 问题真正解决了？

4. 如果修复无效

   • 停下来
   • 计数：你已经尝试了多少次修复？
   • 如果 < 3：回到阶段 1，用新信息重新分析
   • 如果 ≥ 3：停下来质疑架构（见下方第 5 步）
   • 没有架构讨论之前不要尝试第 4 次修复

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

   表明架构问题的模式：

   • 每次修复揭示新的共享状态/耦合/不同位置的问题
   • 修复需要"大规模重构"才能实现
   • 每次修复在其他地方产生新症状

   停下来质疑基本面：

   • 这个模式从根本上是否合理？
   • 我们是否"出于惯性在坚持"？
   • 应该重构架构还是继续修复症状？

   在尝试更多修复之前与用户讨论

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

红旗 — 停下来遵循流程

如果你发现自己在想：

• "先快速修复，之后再调查"
• "试试改 X 看看能不能行"
• "添加多个变更，运行测试"
• "跳过测试，我手动验证"
• "可能是 X，让我修复它"
• "我不完全理解但这可能有效"
• "模式说 X 但我换个方式实现"
• "主要问题有这些：[未经调查就列出修复]"
• 在追踪数据流之前就提出解决方案
• "再试一次修复"（已经试了 2 次以上时）
• 每次修复揭示不同位置的新问题

以上所有都意味着：停下来。回到阶段 1。

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

你做错了的信号

注意这些来自用户的提示：

• "那不是没有发生吗？" — 你假设了但没验证
• "它会给我们展示...吗？" — 你应该添加证据收集
• "别猜了" — 你在没有理解的情况下提出修复
• "深入思考这个" — 质疑基本面，而非只是症状
• "我们卡住了？"（沮丧） — 你的方法不管用

当你看到这些时： 停下来。回到阶段 1。

常见合理化借口

借口	现实
"问题很简单，不需要流程"	简单问题也有根因。流程对简单 bug 也很快。
"紧急情况，没时间走流程"	系统化调试比猜测式乱试更快。
"先试这个，然后再调查"	第一次修复设定了模式。从一开始就做对。
"修复确认有效后再写测试"	未测试的修复不持久。先测试证明它。
"同时修复多个省时间"	无法隔离什么起了作用。会引入新 bug。
"参考太长了，我改编一下模式"	部分理解保证有 bug。完整阅读。
"我看到了问题，让我修复它"	看到症状 ≠ 理解根因。
"再试一次修复"（2 次以上失败后）	3 次以上失败 = 架构问题。质疑模式，而非再次修复。

快速参考

阶段	关键活动	成功标准
1. 根因	阅读错误、复现、检查变更、收集证据	理解了什么和为什么
2. 模式	找到可工作的示例、比较	识别了差异
3. 假设	形成理论、最小化测试	确认或形成新假设
4. 实现	创建测试、修复、验证	Bug 解决，测试通过

当流程揭示"没有根因"

如果系统化调查揭示问题确实是环境性的、时序依赖的或外部的：

1. 你已完成了流程
2. 记录你调查了什么
3. 实现适当的处理（重试、超时、错误消息）
4. 添加监控/日志以供未来调查

但是： 95% 的"没有根因"情况是调查不充分。

配套技术

这些技术是系统化调试的组成部分，位于本目录下：

• root-cause-tracing.md — 通过调用栈反向追踪 bug 以找到原始触发点
• defense-in-depth.md — 找到根因后在多个层添加验证
• condition-based-waiting.md — 用条件轮询替代任意超时

相关 skill：

• test-driven-development — 用于创建失败测试用例（阶段 4，步骤 1）
• verification-before-completion — 在声明成功之前验证修复是否有效

真实世界影响

来自调试会话：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时的乱试
• 一次修复成功率：95% vs 40%
• 引入的新 bug：接近零 vs 常见