dev-debugging

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

系统化调试

概述

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

核心原则： 总是先找到根本原因再尝试修复。症状修复就是失败。

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

铁律

没有先完成第一阶段根本原因调查，就没有修复

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

何时使用

对任何技术问题使用：

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

特别在这些情况下使用：

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

不要在以下情况下跳过：

• 问题看起来简单（简单 bug 也有根本原因）
• 你很匆忙（匆忙保证返工）
• 经理要求立即修复（系统化比瞎折腾快）

四个阶段

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

阶段 1：根本原因调查

尝试任何修复前：

1. 仔细阅读错误消息

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

2. 一致重现

   • 你能可靠触发它吗？
   • 确切步骤是什么？
   • 每次都发生吗？
   • 如果不可重现 → 收集更多数据，不要猜测

3. 检查最近变更

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

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

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

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

   对每个组件边界：
     - 记录什么数据进入组件
     - 记录什么数据离开组件
     - 验证环境/配置传播
     - 检查每层状态
   
   运行一次收集证据显示在哪里中断
   然后分析证据识别失败组件
   然后调查该特定组件
   

5. 追踪数据流

   当错误在调用堆栈深处时：

   • 坏值起源于哪里？
   • 什么用坏值调用了这个？
   • 一直向上追踪直到找到源头
   • 在源头修复，不在症状处

阶段 2：模式分析

修复前找到模式：

1. 找到工作示例

   • 在同一代码库中找到类似工作代码
   • 什么有效且与损坏的相似？

2. 与参考对比

   • 如果实现模式，完整阅读参考实现
   • 不要略读 - 阅读每一行
   • 在应用前完全理解模式

3. 识别差异

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

4. 理解依赖

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

阶段 3：假设和测试

科学方法：

1. 形成单一假设

   • 清楚陈述："我认为 X 是根本原因因为 Y"
   • 写下来
   • 具体，不模糊

2. 最小测试

   • 做最小可能的变更来测试假设
   • 一次一个变量
   • 不要同时修复多个东西

3. 继续前验证

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

4. 当你不知道时

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

阶段 4：实现

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

1. 创建失败测试用例（必须调用 dev-tdd）

   • 读取并遵循 dev-tdd skill
   • 编写 RED 测试：展示 bug 的最小测试
   • 验证 RED：运行测试确认它失败于预期原因
   • 最简单的可能重现
   • 可能的话自动化测试
   • 没有框架时用一次性测试脚本
   • 修复前必须有
   • 使用 dev-tdd skill 编写正确的失败测试

2. 实现单一修复

   • 解决识别的根本原因
   • 一次一个变更
   • 没有"既然我在这里"的改进
   • 没有捆绑重构

3. 验证修复

   • 测试现在通过？
   • 没有其他测试损坏？
   • 问题实际解决？

4. 如果修复无效

   • 停止
   • 计数：你已经尝试了多少修复？
   • 如果 < 3：返回阶段 1，用新信息重新分析
   • 如果 ≥ 3：停止并质疑架构（见下文第 5 步）
   • 不要在没有架构讨论的情况下尝试第 4 个修复

5. 如果 3+ 修复失败：质疑架构

   表示架构问题的模式：

   • 每个修复在不同地方揭示新的共享状态/耦合/问题
   • 修复需要"大规模重构"来实现
   • 每个修复在其他地方制造新症状

   停止并质疑基本原则：

   • 这个模式根本上合理吗？
   • 我们是"因惯性而坚持它"吗？
   • 我们应该重构架构 vs 继续修复症状？

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

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

红旗 - 停止并遵循流程

如果你发现自己在想：

• "暂时快速修复，稍后调查"
• "就试试改 X 看看是否有效"
• "添加多个变更，运行测试"
• "跳过测试，我手动验证"
• "可能是 X，让我修复那个"
• "不完全理解但这个可能有效"
• "模式说 X 但我会不同地适配"
• "主要问题：[列出修复而不调查]"
• 在追踪数据流前提出解决方案
• "再试一次修复"（已经试过 2+ 次）
• 每个修复在不同地方揭示新问题

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

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

常见合理化借口

借口	现实
"问题简单，不需要流程"	简单问题也有根本原因。流程对简单 bug 很快。
"紧急情况，没时间走流程"	系统化调试比猜测检查折腾更快。
"先试试这个，然后再调查"	第一个修复设定模式。从一开始就正确做。
"确认有效后再写测试"	未经测试的修复不持久。先测试证明它。
"同时多个修复节省时间"	无法隔离什么有效。制造新 bug。
"参考太长，我会适配模式"	部分理解保证 bug。完整阅读。
"我看到问题了，让我修复它"	看到症状 ≠ 理解根本原因。

快速参考

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

与 TDD 的集成（关键）

Phase 4 必须使用 dev-tdd

找到根本原因后，不要直接修复。必须使用 TDD：

Phase 4 实施流程：

1. 调用 dev-tdd skill
   ↓
2. RED: 编写失败测试重现 bug
   ↓
3. 验证 RED: 运行测试确认失败于预期原因
   ↓
4. GREEN: 编写最小修复使测试通过
   ↓
5. 验证 GREEN: 运行测试确认通过
   ↓
6. REFACTOR: 清理代码（可选）
   ↓
7. 验证所有测试通过

为什么调试必须使用 TDD

1. 测试证明修复 - 没有测试，你不知道是否真正修复了
2. 测试防止回归 - 同样的 bug 不会再次出现
3. 测试是文档 - 记录了 bug 的行为和修复
4. 强制验证 - RED→GREEN 确保你理解问题

违反 TDD 的红旗

• "我先快速修复，然后再写测试"
• "这个修复很明显，不需要测试"
• "测试太复杂，不值得"
• "我已经手动验证了"

这些都是错误的。必须先有失败测试。

支持技术

• 根本原因追踪 - 向后追踪 bug 通过调用堆栈找到原始触发器
• 深度防御 - 找到根本原因后在多层添加验证

相关 skill：

• dev-tdd - 用于创建失败测试用例（阶段 4，步骤 1）必须调用
• dev-verification - 验证修复有效后再声称成功

真实影响

来自调试会话：

• 系统化方法：15-30 分钟修复
• 随机修复方法：2-3 小时折腾
• 首次修复率：95% vs 40%
• 引入新 bug：接近零 vs 常见