# Code Showcase Systematic Debugging

> 四阶段调试方法论，强调根因分析。用于调查 bug、修复测试失败或排查意外行为时使用。强调未经根因调查不得修复。触发词：系统化调试、调试方法论、bug 修复、根因分析、测试失败、调试流程、故障排查、问题定位、根因调查、四阶段调试、调试铁律。

- Skill: `kscz0000/code-showcase-systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kscz0000/code-showcase-systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/code-showcase-systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: kscz0000 (https://skillmd.com/u/kscz0000)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/kscz0000/code-showcase-systematic-debugging

---


# 系统化调试
## 使用时机

当你需要采用四阶段调试方法论并进行根因分析时使用本技能。在调查 bug、修复测试失败或排查意外行为时使用。强调**未经根因调查不得修复**。


## 核心原则

**未经根因调查，不得修复。**

切勿使用针对症状的补丁掩盖潜在问题。在尝试修复之前，先理解失败的原因。

## 四阶段框架

### 阶段一：根因调查

在动手修改任何代码之前：

1. **仔细阅读错误信息**——每个字都至关重要
2. **稳定复现问题**——如果无法复现，就无法验证修复
3. **检查最近的变更**——问题开始出现之前做了什么改动？
4. **收集诊断证据**——日志、堆栈跟踪、状态转储
5. **追踪数据流**——沿调用链向上回溯，定位无效值的来源

**根因追踪技巧：**
```
1. 观察症状——错误在何处显现？
2. 找出直接原因——哪段代码直接产生了该错误？
3. 追问"谁调用了它"——向上绘制调用链
4. 持续向上追踪——沿调用栈反向追踪无效数据
5. 定位最初触发点——问题真正从何处开始？
```

**关键原则：** 切勿仅在错误显现处修复问题——务必追溯到最初的触发点。

### 阶段二：模式分析

1. **定位可正常工作的示例**——找出表现正确的同类代码
2. **完整对比实现**——不能只是粗略浏览
3. **识别差异**——正常代码与故障代码有何不同？
4. **理解依赖关系**——这段代码依赖哪些东西？

### 阶段三：假设与测试

运用科学方法：

1. **提出一个清晰的假设**——"错误发生的原因是 X"
2. **设计最小化测试**——每次只改变一个变量
3. **预测结果**——若假设正确，应当发生什么？
4. **执行测试**——运行并观察
5. **验证结果**——表现是否与预测一致？
6. **迭代或推进**——假设错误则修正，假设正确则实施

### 阶段四：实施

1. **创建失败的测试用例**——捕获 bug 的行为
2. **实施单一修复**——针对根因而非症状
3. **验证测试通过**——确认修复有效
4. **运行完整测试套件**——确保无回归
5. **若修复失败，立即停止**——重新评估假设

**关键规则：** 若连续三次或以上修复失败，立即停止。这表明存在需要讨论的架构问题，而非再加一层补丁。

## 危险信号——流程违规

若察觉自己有以下念头，立即停下：

- "先快速修一下，稍后再调查"
- （在多次失败后）"再试一次修复"
- "这个应该能行"（却未理解原因）
- "我就试试……"（未提出假设）
- "在我机器上是好的"（却未调查差异）

## 深层问题的警示信号

**连续修复在不同区域暴露新问题**，表明存在架构层面的问题：

- 停止打补丁
- 记录已发现的情况
- 与团队讨论后再继续
- 思考是否需要重新审视设计

## 常见调试场景

### 测试失败

```
1. 阅读完整的错误信息与堆栈跟踪
2. 定位是哪条断言失败及其原因
3. 检查测试设置——测试环境是否正确？
4. 检查测试数据——mock/夹具是否正确？
5. 追溯到异常值的来源
```

### 运行时错误

```
1. 捕获完整的堆栈跟踪
2. 定位抛错的代码行
3. 检查哪些值为 undefined/null
4. 向上回溯，找到异常值的来源
5. 在源头添加校验
```

### "之前是正常的"

```
1. 使用 git bisect 定位引入问题的提交
2. 将当前变更与之前可工作的版本对比
3. 识别哪些假设发生了变化
4. 在假设被违反的源头进行修复
```

### 间歇性失败

```
1. 排查竞争条件
2. 检查共享的可变状态
3. 检查异步操作的执行顺序
4. 排查时序依赖
5. 添加确定性等待或适当的同步机制
```

## 调试检查清单

在声称 bug 已修复之前：

- [ ] 已识别并记录根因
- [ ] 已形成并测试假设
- [ ] 修复针对根因而非症状
- [ ] 已创建可复现 bug 的失败测试
- [ ] 应用修复后测试已通过
- [ ] 完整测试套件通过
- [ ] 未使用"快速修复"的自我开脱
- [ ] 修复最小化且聚焦

## 成效指标

系统化调试的首修成功率约为 95%，相比之下临时拼凑式约为 40%。

做得对的标志：
- 修复不会引发新 bug
- 能够解释 bug 发生的**原因**
- 类似 bug 不会再次出现
- 修复后代码更佳，而非仅"可用"

## 与其他技能的集成

- **testing-patterns**：先创建能复现 bug 的测试，再进行修复

## 局限性

- 仅当任务明确匹配其上游来源与本地项目上下文时使用本技能。
- 在应用变更前，验证命令、生成的代码、依赖、凭证以及外部服务的行为。
- 切勿将示例视为环境特定测试、安全审查或用户对破坏性/高成本操作授权的替代。