---

name: 系统化调试 description: 在提出修复方案前找出根本原因的四个阶段调试框架。适用于调查bug、错误、意外行为、测试失败，或之前修复未奏效的情况。

系统化调试

核心原则： 在尝试修复前找出根本原因。仅处理症状的修复是失败的。

四个阶段

每个阶段完成后再进入下一个阶段。

调试进度：
- [ ] 阶段1：根因调查
- [ ] 阶段2：模式分析
- [ ] 阶段3：假设测试
- [ ] 阶段4：实施

阶段1：根因调查

在尝试任何修复前：

1. 仔细阅读错误消息 - 堆栈跟踪通常包含解决方案
2. 一致地重现问题 - 如果无法重现，则收集更多数据
3. 检查近期变更 - Git diff、新依赖、配置更改
4. 反向追踪数据流 - 找出无效数据的起源

对于多组件系统： 在每个组件边界添加诊断日志，然后再提出修复方案。参考references/debugging-techniques.md获取检测模式。

对于日志密集型调查： 使用Skill(ce:reading-logs)进行高效分析。

阶段2：模式分析

1. 在代码库中查找类似代码的工作示例
2. 比较工作与损坏代码 - 列出所有差异
3. 完整阅读参考实现，而非草草略过

阶段3：假设测试

1. 形成单一假设：“X是根本原因，因为Y”
2. 进行最小可能的更改来测试它
3. 在继续前验证 - 如果错误，形成新假设

阶段4：实施

1. 首先创建失败的测试用例
2. 在根本原因处实施单一修复
3. 应用深度防御 - 在多个层验证
4. 验证修复并运行测试

如果3个以上修复失败： 停止修复症状。质疑架构。

红旗警示

如果发现自己有以下行为，请停止并返回阶段1：

• 未完成调查就提出修复
• “只是试试更改X看看是否有效”
• 一次添加多个更改
• “可能是X，让我修复它”（无证据）
• 每次修复都揭示不同地方的新问题

战术技巧

对于特定调试方法，参考references/debugging-techniques.md：

• 二分搜索 / git bisect
• 最小复现
• 战略日志记录
• 运行时断言
• 差异分析
• 多组件检测
• 反向追踪

报告格式

## 根因
[1-3句话解释潜在问题]
位置：`file.ts:123`

## 错误所在
[具体问题 - 突变、竞态条件、缺少验证等]

## 修复方案
[所做的更改以及它们如何解决根本原因]

## 验证
- [x] 错误已复现并确认修复
- [x] 现有测试通过
- [x] 添加回归测试