Systematic Debugging

系统化调试

基于 obra/superpowers 的调试方法论。

核心原则

> 永远先找到根本原因，再尝试修复。症状修复是失败的。

触发条件

当用户遇到 Bug、错误、或需要排查问题时激活。

调试流程

阶段1：问题定义

1. 明确预期行为是什么
2. 明确实际行为是什么
3. 确定问题的可复现步骤
4. 记录环境信息（版本、配置等）

阶段2：信息收集

1. 收集错误日志和堆栈信息
2. 确定问题首次出现的时间
3. 识别最近的代码变更
4. 检查相关配置和依赖

阶段3：假设形成

1. 基于信息提出可能的原因
2. 按可能性排序
3. 设计验证方案

阶段4：假设验证

1. 一次只验证一个假设
2. 使用最小化测试用例
3. 记录验证结果
4. 排除或确认假设

阶段5：根因确认

1. 确认找到的是根本原因，不是症状
2. 验证修复方案能解决问题
3. 确保不引入新问题

阶段6：修复与验证

1. 实施最小化修复
2. 编写回归测试
3. 验证修复效果
4. 文档记录

输出格式

# 🐛 调试报告

## 问题描述
- **预期行为**：[描述]
- **实际行为**：[描述]
- **复现步骤**：
  1. [步骤1]
  2. [步骤2]
  3. [步骤3]

## 环境信息
- **系统**：[OS版本]
- **运行时**：[Node/Python/Java版本]
- **依赖版本**：[关键依赖]

## 错误信息

[错误日志/堆栈信息]

## 调查过程

### 假设1：[假设描述]
- **验证方法**：[如何验证]
- **结果**：✅ 确认 / ❌ 排除
- **证据**：[支持结论的证据]

### 假设2：[假设描述]
- **验证方法**：[如何验证]
- **结果**：✅ 确认 / ❌ 排除
- **证据**：[支持结论的证据]

## 根本原因
[详细说明根本原因]

## 修复方案
```[语言]
// 修复代码

验证结果

• [ ] 问题已修复
• [ ] 回归测试通过
• [ ] 无新问题引入

预防措施

[如何避免类似问题再次发生]

## 常见调试技巧

### 二分法定位

1. 确定问题存在的范围
2. 将范围一分为二
3. 确定问题在哪一半
4. 重复直到定位到具体位置

### 最小化复现

1. 从完整场景开始
2. 逐步移除无关代码/配置
3. 直到找到最小复现用例
4. 最小用例更容易分析

### 橡皮鸭调试

1. 向"橡皮鸭"解释代码逻辑
2. 逐行解释代码在做什么
3. 解释过程中往往能发现问题

### 日志追踪

1. 在关键节点添加日志
2. 记录输入、输出、状态
3. 通过日志追踪执行流程
4. 定位异常发生位置

## 常见陷阱

### ❌ 避免
- 不理解问题就开始修复
- 同时修改多处代码
- 假设问题原因而不验证
- 只修复症状不找根因
- 修复后不验证

### ✅ 建议
- 先复现，再分析
- 一次只改一处
- 用证据支持结论
- 找到根本原因
- 编写回归测试

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [5tldr](https://github.com/5tldr)
- **Source:** [5tldr/claude-skills](https://github.com/5tldr/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.