# Systematic Debugging

> 当遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前

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

---


# 系统化调试

## 概述

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

**核心原则：** 在尝试修复之前始终找到根本原因。修复症状是失败。

**违反此流程的字面意思就是违反调试的精神。**

## 铁律

```
没有根本原因调查就不能修复
```

如果你还没有完成阶段 1，就不能提出修复方案。

## 何时使用

用于任何技术问题：
- 测试失败
- 生产环境 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题

**特别在以下情况使用：**
- 时间压力下（紧急情况使猜测变得诱人）
- "只是一个快速修复"看起来很明显
- 你已经尝试了多种修复
- 之前的修复不起作用
- 你不完全理解问题

**不要跳过：**
- 问题看起来简单（简单的 bug 也有根本原因）
- 你很着急（匆忙保证返工）
- 经理要求立即修复（系统化比盲目尝试更快）

## 四个阶段

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

### 阶段 1：根本原因调查

**在尝试任何修复之前：**

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

2. **一致地复现**
   - 你能可靠地触发它吗？
   - 确切的步骤是什么？
   - 每次都发生吗？
   - 如果不可复现 → 收集更多数据，不要猜测

3. **检查最近的更改**
   - 什么变化可能导致这个问题？
   - Git diff、最近的提交
   - 新依赖、配置更改
   - 环境差异

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

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

   **在提出修复之前，添加诊断埋点：**
   ```
   对于每个组件边界：
     - 记录进入组件的数据
     - 记录离开组件的数据
     - 验证环境/配置传播
     - 检查每层的状态

   运行一次收集证据，显示在哪里中断
   然后分析证据识别故障组件
   然后调查该特定组件
   ```

   **示例（多层系统）：**
   ```bash
   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"

   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   **这揭示：** 哪层失败（secrets → workflow ✓, workflow → build ✗）

5. **追踪数据流**

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

   请参阅本目录中的 `root-cause-tracing.md` 了解完整的向后追踪技术。

   **快速版本：**
   - 错误值从哪里来？
   - 谁用错误值调用了这个？
   - 继续向上追踪直到找到源头
   - 在源头修复，而非症状

### 阶段 2：模式分析

**在修复之前找到模式：**

1. **找到工作示例**
   - 在同一代码库中找到类似的正常工作代码
   - 有什么与损坏的相似但正常工作？

2. **与参考对比**
   - 如果实现模式，完整阅读参考实现
   - 不要略读 - 阅读每一行
   - 在应用前完全理解模式

3. **识别差异**
   - 正常工作和损坏之间有什么不同？
   - 列出每个差异，无论多小
   - 不要假设"那不可能重要"

4. **理解依赖**
   - 这需要什么其他组件？
   - 什么设置、配置、环境？
   - 它做什么假设？

### 阶段 3：假设和测试

**科学方法：**

1. **形成单一假设**
   - 清楚陈述："我认为 X 是根本原因，因为 Y"
   - 写下来
   - 要具体，不要模糊

2. **最小化测试**
   - 做最小的可能更改来测试假设
   - 一次一个变量
   - 不要同时修复多个东西

3. **验证后再继续**
   - 起作用了吗？是 → 阶段 4
   - 没起作用？形成新假设
   - 不要在上面添加更多修复

4. **当你不知道时**
   - 说"我不理解 X"
   - 不要假装知道
   - 寻求帮助
   - 更多研究

### 阶段 4：实现

**修复根本原因，而非症状：**

1. **创建失败测试用例**
   - 最简单的可能复现
   - 尽可能自动化测试
   - 如果没有框架则用一次性测试脚本
   - 修复前必须有
   - 使用 `zjkycode:test-driven-development` 技能编写正确的失败测试

2. **实现单一修复**
   - 解决识别的根本原因
   - 一次一个更改
   - 没有"顺便"改进
   - 没有捆绑重构

3. **验证修复**
   - 测试现在通过了吗？
   - 没有其他测试被破坏？
   - 问题真的解决了？

4. **如果修复不起作用**
   - 停止
   - 计数：你尝试了多少次修复？
   - 如果 < 3：返回阶段 1，用新信息重新分析
   - **如果 ≥ 3：停止并质疑架构（下面的步骤 5）**
   - 不要在没有架构讨论的情况下尝试第 4 次修复

5. **如果 3 次以上修复失败：质疑架构**

   **表明架构问题的模式：**
   - 每次修复都在不同地方揭示新的共享状态/耦合/问题
   - 修复需要"大规模重构"才能实现
   - 每次修复在其他地方创建新症状

   **停止并质疑基础：**
   - 这个模式根本上合理吗？
   - 我们是否"纯粹靠惯性坚持"？
   - 我们应该重构架构 vs. 继续修复症状？

   **在尝试更多修复之前与你的伙伴讨论**

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

## 危险信号 - 停止并遵循流程

如果你发现自己在想：
- "暂时快速修复，以后再调查"
- "只是尝试改变 X 看看是否有效"
- "添加多个更改，运行测试"
- "跳过测试，我会手动验证"
- "可能是 X，让我修复那个"
- "我不完全理解但这可能有效"
- "模式说 X 但我会不同地适应"
- "这是主要问题：[列出修复而没有调查]"
- 在追踪数据流之前提出解决方案
- **"再尝试一次修复"（当已经尝试 2 次以上）**
- **每次修复在不同地方揭示新问题**

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

**如果 3 次以上修复失败：** 质疑架构（见阶段 4.5）

## 你的伙伴发出的错误信号

**注意这些重定向：**
- "那没有发生吗？" - 你没有验证就假设了
- "它会显示我们...吗？" - 你应该添加证据收集
- "停止猜测" - 你在没有理解的情况下提出修复
- "深度思考这个" - 质疑基础，不只是症状
- "我们卡住了？"（沮丧）- 你的方法不起作用

**当你看到这些：停止。返回阶段 1。**

## 常见合理化

| 借口 | 现实 |
|------|------|
| "问题很简单，不需要流程" | 简单问题也有根本原因。流程对简单 bug 很快。 |
| "紧急情况，没时间走流程" | 系统化调试比猜测检查的盲目尝试更快。 |
| "先尝试这个，然后调查" | 第一次修复设定模式。从一开始就做对。 |
| "我会在确认修复有效后写测试" | 未测试的修复不会持久。测试先证明它。 |
| "一次多个修复节省时间" | 无法隔离什么有效。导致新 bug。 |
| "参考太长，我会适应模式" | 部分理解保证 bug。完整阅读。 |
| "我看到问题了，让我修复它" | 看到症状 ≠ 理解根本原因。 |
| "再尝试一次修复"（2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要再修复。 |

## 快速参考

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

## 当流程揭示"没有根本原因"

如果系统化调查揭示问题确实是环境、时序依赖或外部的：

1. 你已完成流程
2. 记录你调查了什么
3. 实现适当的处理（重试、超时、错误消息）
4. 添加监控/日志用于未来调查

**但是：** 95% 的"没有根本原因"案例是不完整的调查。

## 支持技术

这些技术是系统化调试的一部分，可在本目录中找到：

- **`root-cause-tracing.md`** - 通过调用栈向后追踪 bug 以找到原始触发点
- **`defense-in-depth.md`** - 在找到根本原因后在多层添加验证
- **`condition-based-waiting.md`** - 用条件轮询替换任意超时

**相关技能：**
- **zjkycode:test-driven-development** - 用于创建失败测试用例（阶段 4，步骤 1）
- **zjkycode:verification-before-completion** - 在声称成功之前验证修复有效

## 实际影响

来自调试会话：
- 系统化方法：15-30 分钟修复
- 随机修复方法：2-3 小时的盲目尝试
- 首次修复率：95% vs 40%
- 引入新 bug：接近零 vs 常见