interrogation-debugging

审讯：系统化调试

概述

随机修复会浪费时间，还会引入新 Bug。匆忙打补丁，只会让真正的祸根逍遥法外。

核心原则： 尝试修复之前，务必找出根本原因。只修复症状是无效的。

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

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果你还没有完成《简报》，就不能提出修复方案。这是沉默法则。

适用场景

遇到任何技术问题时都使用：

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

尤其适用于以下情况：

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

以下情况也不要跳过：

• 问题看起来很简单（简单的 Bug 也有根本原因）
• 你很赶时间（仓促行事必然导致返工）
• 老大要求你现在就修好（系统化处理比瞎折腾更快）

四个阶段

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

简报

尝试任何修复之前：

1. 阅读证据

   • 不要略过错误或警告
   • 它们通常会直接指出解决方案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径和错误代码

2. 重现现场

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

3. 检查近期变更

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

4. 在每个边界收集证据

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

   提出修复方案之前，先添加诊断插桩：

   对每个组件边界：

   • 记录进入组件的数据
   • 记录离开组件的数据
   • 验证环境和配置是否正确传递
   • 检查每一层的状态

   运行一次，收集证据，确定问题出在哪里。 然后分析证据，找出故障组件。 接着调查该组件。

5. 追踪数据流

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

   • 错误值从哪里产生？
   • 是谁用这个错误值调用了当前代码？
   • 持续向前追溯，直到找到源头
   • 从源头修复，而不是只处理症状

交叉审查

修复之前先找出规律：

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

   • 在同一代码库中找到类似的正常代码
   • 哪些代码能够正常工作，且与出问题的代码相似？

2. 对照参考实现

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

3. 找出差异

   • 正常代码与出问题的代码有什么不同？
   • 列出所有差异，无论多么细微
   • 不要想当然地认为“这不可能有影响”

4. 理解依赖项

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

理论

科学方法：

1. 提出单一假设

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

2. 进行最小化测试

   • 只做最小的改动来验证假设
   • 一次只改变一个变量
   • 不要一次修复多个问题

3. 确认后再继续

   • 是否奏效？是 → 一击命中
   • 没有奏效？提出新的假设
   • 不要在现有修复上继续叠加更多修复

4. 不知道时

   • 说“我不理解 X”
   • 不要假装自己知道
   • 寻求帮助或进一步调查

命中问题

修复根因，而不是症状：

1. 创建失败用例

   • 尽可能简单地复现问题
   • 尽可能编写自动化测试
   • 如果没有测试框架，就编写一次性测试脚本
   • 修复前必须先完成
   • 使用 gangsta:drill-tdd 编写规范的失败测试

2. 实施单一修复

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

3. 验证修复

   • 测试现在是否通过？
   • 是否有其他测试失败？
   • 问题是否确实解决？
   • 使用 gangsta:sweep-verification 进行验证后再宣称成功

4. 如果修复无效

   • 停止
   • 统计：你尝试了多少次修复？
   • 如果少于 3 次：返回问题简述，根据新信息重新分析
   • 如果 ≥ 3 次：停止并升级处理（见下面的第 5 步）
   • 未经架构讨论，不要尝试第 4 次修复

5. 如果 3 次或更多修复都失败：升级给 Don

   表明架构已经腐朽的模式：

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

   停止并质疑根本问题：

   • 这种模式从根本上是否合理？
   • 我们是否只是因为惯性而继续沿用它？
   • 应该重构架构，还是继续修复症状？

   尝试更多修复前，先与 Don 讨论。

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

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

如果你发现自己在想：

想法	实际情况
“先快速修复，之后再调查”	现在就调查。快速修复会造成问题叠加。
“先改一下 X 看看”	这是猜测，不是调试。回到问题简述。
“做多项更改后再运行测试”	无法确定哪项更改起了作用。一次只做一项。
“跳过测试，我会手动验证”	手动验证不是证据。
“问题大概出在 X，我来修一下”	“大概”说明你还没有调查清楚。
“我还没完全弄懂，但这样或许有用”	“或许”就是猜测。回到问题简述。
“再试一次修复”（已经尝试 2 次或更多）	失败 3 次说明存在架构问题。升级处理。
“主要问题如下：[列表]”	不经调查就列出问题，无效。
追踪数据流之前就提出解决方案	停止。先追踪，再提出方案。

以上任何一种情况都意味着：停止。返回问题简述。

Don 提醒你做错事时的信号

留意这些纠正：

• “没有发生这种情况吗？”——你未经验证就做了假设
• “这能让我们看到……吗？”——你本应添加证据收集步骤
• “别猜了”——你不了解情况就提出了修复方案
• “再深入想想”——质疑根本问题，而不只是症状
• “我们卡住了吗？”（语气沮丧）——你的方法不起作用

**看到这些信号时：**停止。返回问题简述。

常见自我开脱

借口	实际情况
“问题很简单，不需要流程”	简单问题也有根因。处理简单错误时，流程同样高效。
“情况紧急，没时间走流程”	系统化调试比反复猜测和试错更快。
“先试试这个，再调查”	第一次修复会决定后续做法。从一开始就按正确方式处理。
“确认修复有效后再写测试”	未经测试的修复无法保证有效。先写测试才能验证。
“一次做多个修复更省时间”	无法确定哪项起了作用，还可能引入新错误。
“参考内容太长，我会自行调整做法”	只理解一部分必然导致错误。请完整阅读。
“我看出问题了，让我来修”	看到症状 ≠ 理解根因。
“再试一次修复”（已经失败 2 次或更多）	失败 3 次或更多说明存在架构问题。升级给 Don。

快速参考

阶段	关键活动	成功标准
简报	阅读错误信息、复现问题、检查变更、收集证据	理解是什么以及为什么
交叉盘问	查找可正常运行的示例并进行比较	找出差异
形成理论	提出假设并进行最小化测试	确认假设或提出新假设
出击	创建测试、修复问题、验证结果	Bug 已解决，测试通过

调查未能发现根本原因时

如果系统调查表明，问题确实由环境导致、取决于时序或源自外部：

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

但是： 95% 的“未找到根本原因”案例，都是因为调查不完整。

相关技能

• gangsta:drill-tdd — 用于创建失败的测试用例（出击，第 1 步）
• gangsta:sweep-verification — 在宣告成功前验证修复是否生效

Omerta 合规性

• 真实原则：所有发现均引用具体代码、错误输出或证据
• 规范即法律：修复必须追溯到已诊断的根本原因，而非凭空猜测