---
source: ../../../core/systematic-debugging.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-03-24
status: current
---

> **语言**: [English](../../../core/systematic-debugging.md) | 简体中文

# 系统化调试工作流

**版本**: 1.0.0
**最后更新**: 2026-03-20
**适用范围**: 所有使用 AI 辅助开发的软件项目
**范围**: universal
**灵感来源**: [Superpowers](https://github.com/obra/superpowers) — systematic-debugging (MIT)

---

## 目的

定义结构化的四阶段调试工作流，防止常见的"猜测修复"反模式。强制要求在尝试修复前先进行根因分析，并包含 **3-Strike Rule** 以提早发现架构问题。

---

## 术语表

| 术语 | 定义 |
|------|------|
| 根因 | 缺陷存在的根本原因，而非仅仅是症状 |
| 3-Strike Rule | 连续 3 次修复尝试失败后，怀疑架构问题 |
| 反向追踪 | 从错误症状追溯到产生源头 |
| 组件边界 | 两个模块或子系统之间的接口 |

---

## 核心原则 — 铁律

> **禁止跳过根因分析直接修复。**

如果你发现自己在说"快速修复"、"试试看"或"现在应该可以了" — **停下来**，回到阶段 1。

---

## 四个阶段

### 阶段 1：根因调查

分析错误消息并追踪最近变更，形成初步假设。

1. **仔细阅读错误** — 识别失败的确切位置和类型
2. **追踪最近变更** — 使用 `git log`、`git diff`、`git blame` 查找变更内容
3. **在组件边界添加诊断** — 在模块接口处插入日志/断点
4. **记录观察** — 记录所见并形成初步假设

### 阶段 2：模式分析

将失败代码与类似的成功实现进行比较。

1. **搜索类似的成功实现** — 在代码库中查找
2. **识别差异** — 比较失败和成功代码之间的不同
3. **检查最近的变更** — 确认是否有回归引入
4. **验证假设** — 通过额外的日志/测试确认

### 阶段 3：修复实施

基于确认的根因实施修复。

1. **先写测试** — 创建复现问题的失败测试
2. **实施最小修复** — 只修改必需的内容
3. **验证修复** — 测试现在应通过
4. **检查副作用** — 运行完整测试套件

### 阶段 4：回顾

防止类似问题再次发生。

1. **记录根因** — 在提交消息中说明
2. **评估是否需要额外测试** — 防止回归
3. **检查是否有类似模式** — 其他地方是否有同样的问题

---

## 3-Strike Rule

| 尝试 | 动作 |
|------|------|
| 第 1 次失败 | 重新审视假设，添加更多诊断 |
| 第 2 次失败 | 扩大调查范围，考虑上游原因 |
| 第 3 次失败 | **停止** — 怀疑架构问题，寻求审查 |

连续 3 次修复失败后，问题很可能不在你认为的地方。需要退后一步，重新审视整体架构。

---

## 相关标准

- [验证证据](verification-evidence.md)
- [测试标准](testing-standards.md)

---

## 许可证

本标准采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
