名称: 系统化调试描述: 当遇到任何 bug、测试失败或意外行为时使用，在提出修复之前

系统化调试

概述

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

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

违反此流程的文字就是违反调试的精神。

铁律

在没有完成第一阶段的情况下，不能提出修复

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

何时使用

用于任何技术问题：

测试失败
生产中的 bug
意外行为
性能问题
构建失败
集成问题

特别在以下情况使用此流程：

时间紧迫时（紧急情况使猜测变得诱人）
“只需一个快速修复” 看起来很显而易见
你已经尝试了多种修复
之前的修复没有生效
你没有完全理解问题

不要跳过，当：

问题看似简单（简单的 bug 也有根本原因）
你在匆忙中（匆忙保证需要重新工作）

四个阶段

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

阶段 1: 根本原因调查

在尝试任何修复之前：

仔细阅读错误消息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完全读取堆栈跟踪
- 注意行号、文件路径、错误代码
一致地重现
- 你能可靠地触发它吗？
- 确切的步骤是什么？
- 每次都会发生吗？
- 如果不能重现 → 收集更多数据，不要猜测
检查最近的变化
- 什么改变可能导致这个问题？
- Git diff、最近提交
- 新依赖、配置更改
- 环境差异

在多组件系统中收集证据

当系统有多个组件时：

在提出修复之前，添加诊断工具：

对于每个组件边界：
  - 记录数据进入组件的内容
  - 记录数据退出组件的内容
  - 验证环境/配置传播
  - 检查每个层的状态

运行一次以收集证据，显示在哪里中断
然后分析证据以识别失败组件
然后调查那个特定组件

追踪数据流
- 坏值从哪里起源？
- 谁用坏值调用了这个？
- 持续向上追踪，直到找到源头
- 在源头修复，而不是在症状处

阶段 2: 模式分析

在修复之前找到模式：

找到工作示例 — 在相同代码库中定位类似工作代码
与参考实现比较 — 完全读取参考实现
识别差异 — 列出每一个差异，无论多小
理解依赖关系 — 这需要哪些其他组件？

阶段 3: 假设和测试

科学方法：

形成单一假设 — “我认为 X 是根本原因，因为 Y”
最小化测试 — 做最小的可能更改来测试假设
在继续之前验证 — 它生效了吗？是 → 阶段 4。否 → 形成新假设
当你不理解时 — 说 “我不理解 X”。不要假装知道。

阶段 4: 实施

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

创建失败测试案例 — 最简单的可能重现。必须在修复之前拥有。
实施单一修复 — 解决根本原因。一次只做一个更改。
验证修复 — 测试通过了吗？没有其他测试被破坏吗？问题实际上解决了吗？
如果修复不生效 — 停止。计算尝试的修复次数。如果 ≥ 3：质疑架构。
如果 3+ 修复失败：质疑架构
- 这个模式从根本上来说合理吗？
- 我们应该重构架构而不是继续修复症状吗？
- 在尝试更多修复之前与用户讨论

红旗 — 停止并遵循流程

如果你发现自己这样想：

“现在快速修复，稍后调查”
“只需尝试改变 X，看看是否生效”
“添加多个更改，运行测试”
“可能是 X，让我修复那个”
“我没有完全理解，但这可能生效”
“再尝试一次修复”（当已经尝试了 2+ 次）

所有这些意味着：停止。返回到阶段 1。

常见合理化

借口	现实
“问题简单，不需要流程”	简单的问题也有根本原因。
“紧急情况，没时间走流程”	系统化调试比猜测和检查更快。
“先尝试这个，然后调查”	第一次修复设定了模式。从一开始就做对。
“一次做多个修复节省时间”	无法隔离哪个生效了。导致新 bug。
“我看到问题了，让我修复它”	看到症状 ≠ 理解根本原因。
“再尝试一次修复”（在 2+ 次失败后）	3+ 次失败 = 架构问题。

快速参考

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

相关技能:

oac:verification-before-completion — 在声称成功之前验证修复生效
oac:test-generation — 用于创建失败测试案例（阶段 4，步骤 1）

名称: 系统化调试 描述: 当遇到任何 bug、测试失败或意外行为时使用，在提出修复之前