# Systematic Debugging

> 4 阶段根因调试：在修复之前理解 bug。

- Skill: `tencentcloud/systematic-debugging` (Agent Skill)
- Install (CLI): `npx get-skill add tencentcloud/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencentcloud/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: tencentcloud (https://skillmd.com/u/tencentcloud)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/tencentcloud/systematic-debugging

---


# 系统性调试

## Harness-agent 工具

本技能从 Octop 移植。使用以下 harness/deepagents 工具：

| 概念 | 工具 |
|---------|------|
| Shell | `execute` |
| 读/写/编辑文件 | `read_file`, `write_file`, `edit_file` |
| 查找文件/搜索内容 | `glob`, `grep` |
| 获取 URL | `web_fetch` |
| 浏览器自动化 | `browser_use` |
| 子代理工作 | `task` |
| 记忆 | `memory_store`, `memory_recall`, `memory_search` |

内置技能文件位于 `/_builtin_skills/<name>/`。用户安装的技能位于 `/skills/<name>/`。

## 概述

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

**核心原则：** 始终先找到根因，再尝试修复。症状修复就是失败。

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

## 铁律

```
没有根因调查就禁止修复
```

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

## 反馈循环规则

反馈循环就是调试工作。在阅读代码建立理论之前，先创建或确定一个**紧密的**命令，它能在用户的确切症状上变红，并在 bug 修复后变绿。紧密循环是快速的、确定性的、可由代理运行的，并且足够具体以捕获此 bug——而不仅仅是"不崩溃"。

当干净的复现很困难时，投入不成比例的努力来构建循环。在没有红色能力的循环的情况下猜测，正是此技能旨在防止的失败模式。

## 何时使用

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

**特别要使用当：**
- 时间紧迫时（紧急情况让人想猜测）
- "就一个快速修复"看起来很明显
- 你已经尝试了多个修复
- 之前的修复没有奏效
- 你不完全理解问题

**不要跳过当：**
- 问题看起来简单（简单 bug 也有根因）
- 你很匆忙（仓促保证返工）
- 有人希望它立即修复（系统性的比折腾更快）

## 四个阶段

你必须在继续下一个之前完成每个阶段。

---

## 阶段1：根因调查

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

### 1. 仔细阅读错误消息

- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 注意行号、文件路径、错误代码

**行动：** 使用 `read_file` 读取相关源文件。使用 `glob` 在代码库中查找错误字符串。

### 2. 构建紧密反馈循环

- 你能用一个命令触发用户的确切症状吗？
- 命令对这个 bug 失败，并且只在 bug 修复后通过吗？
- 它足够快可以重复运行吗？
- 它是确定性的吗？对于不稳定的 bug，你能将复现率提高到足够高以进行调试吗？
- 如果不可复现 → 收集更多数据，不要猜测。

**构建循环的方法——大致按此顺序尝试：**

1. **失败测试**在触及 bug 的接缝处：单元测试、集成测试或端到端测试。
2. **HTTP 脚本/curl** 针对运行中的开发服务器。
3. **CLI 调用**带有固定输入，将 stdout/stderr 与预期输出进行 diff。
4. **无头浏览器脚本**（Playwright/Puppeteer）对 DOM、控制台或网络进行断言。
5. **重放捕获的跟踪**：HAR、请求负载、事件日志、队列消息或 webhook 主体。
6. **一次性 harness**启动系统的最小有用切片并调用失败路径。
7. **属性/模糊循环**当 bug 在广阔输入空间上间歇性错误输出时。
8. **二分 harness**适用于 `git bisect run`，当 bug 出现在两个已知状态之间时。
9. **差分循环**比较旧版本与新版本、两个配置、两个提供者或两个数据集。
10. **人在回路脚本**仅作为最后手段：脚本化人的步骤并捕获其结果，以便循环保持结构化。

**循环存在后收紧它：**

- 让它更快：缓存设置、缩小范围、跳过无关初始化。
- 让信号更清晰：断言确切症状，而不是通用成功。
- 让它更确定性：固定时间、种子随机性、隔离文件系统、冻结网络。

对于非确定性 bug，直接目标是更高的复现率，而不是完美。运行触发器 100 次、并行化、增加压力、缩小时间窗口或注入睡眠。50% 的 flake 是可调试的；1% 的 flake 通常不是。

**行动：** 使用 `execute` 工具运行紧密循环：

```bash
# 运行特定的失败测试
pytest tests/test_module.py::test_name -v

# 或运行脚本化复现
python scripts/repro_bug.py

# 或运行高重复不稳定复现
for i in {1..100}; do pytest tests/test_flake.py::test_name -q || break; done
```

### 3. 检查最近更改

- 什么更改可能导致此问题？
- Git diff、最近提交
- 新依赖项、配置更改

**行动：**

```bash
# 最近提交
git log --oneline -10

# 未提交的更改
git diff

# 特定文件中的更改
git log -p --follow src/problematic_file.py | head -100
```

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

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

**在提出修复之前，添加诊断工具：**

对于每个组件边界：
- 记录什么数据进入组件
- 记录什么数据离开组件
- 验证环境/配置传播
- 检查每层的状态

运行一次以收集显示其在何处中断的证据。
然后分析证据以识别失败的组件。
然后调查该特定组件。

### 5. 追踪数据流

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

- 坏值起源于哪里？
- 谁用坏值调用了此函数？
- 继续向上追踪直到找到源头
- 在源头修复，而不是在症状处修复

**行动：** 使用 `glob` 追踪引用：

```text
# 查找函数被调用的位置
grep(pattern="function_name\\(", path="src/")

# 查找变量被设置的位置
grep(pattern="variable_name\\s*=", path="src/")
```

### 阶段1 完成检查清单

- [ ] 错误消息已完整阅读和理解
- [ ] 存在紧密循环命令并已运行至少一次
- [ ] 循环能够变红：它断言用户的确切症状，而不是附近失败
- [ ] 循环是确定性的，或者不稳定 bug 有足够高的复现率来调试
- [ ] 已识别并审查最近更改
- [ ] 已收集证据（日志、状态、数据流）
- [ ] 问题隔离到特定组件/代码
- [ ] 根因假设可以陈述和测试

**停止：** 在你理解*为什么*发生之前，不要进入阶段2。

---

## 阶段2：模式分析

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

### 0. 最小化复现

一旦循环变红，将复现缩小到仍然变红的最小场景。逐个削减输入、调用者、配置、数据和步骤，**每次削减后重新运行循环。只保留对失败有负载的内容。

当移除任何剩余元素都会使循环变绿时完成。最小复现缩小了假设空间，并且通常成为最干净的回归测试。

### 1. 找到工作示例

- 在同一代码库中找到类似的工作代码
- 什么工作是类似于损坏的东西？

**行动：** 使用 `glob` 找到可比较的模式：

```python
grep(pattern="similar_pattern", path="src/")
```

### 2. 与参考对比

- 如果实施模式，请**完整**阅读参考实现
- 不要略读——阅读每一行
- 在应用之前完全理解模式

### 3. 识别差异

- 工作的和损坏的之间有什么不同？
- 列出每一个差异，无论多小
- 不要假设"那不可能重要"

### 4. 理解依赖

- 这需要什么其他组件？
- 什么设置、配置、环境？
- 它做了什么假设？

---

## 阶段3：假设和测试

**科学方法：**

### 1. 形成排名的可证伪假设

- 在测试任何一个之前，生成 3-5 个合理的假设。
- 按可能性和证伪成本对它们排名。
- 陈述每个假设做出的预测："如果 X 是原因，那么改变或观察 Y 应该使 Z 发生。"
- 丢弃或 sharpen 任何不能做出可测试预测的假设。

如果用户在场，在测试之前显示排名列表。他们可能拥有可以立即重新排名的领域知识。如果用户 AFK，继续你的排名。

### 2. 最小化测试

- 用最小可能的探测测试排名最高的假设。
- 一次更改一个变量。
- 不要一次修复多个东西。
- 优先使用调试器/REPL 检查（当可用时）；一个断点胜过十个日志。
- 如果添加日志，用唯一前缀（如 `[DEBUG-a4f2]`）标记每一行临时行，以便清理是单次搜索。

### 3. 继续前验证

- 有效吗？→ 阶段4
- 无效？→ 形成新的假设
- **不要**在顶部添加更多修复

### 4. 当你不知道时

- 说"我不理解 X"
- 不要假装知道
- 向用户寻求帮助
- 更多研究

---

## 阶段4：实施

**修复根因，而不是症状：**

### 1. 创建失败测试用例

- 尽可能简单的复现
- 如果可能，自动化测试
- 修复之前必须有
- 使用 `test-driven-development` 技能

### 2. 实施单一修复

- 解决已识别的根因
- 一次一个更改
- 没有"趁我在场"的改进
- 没有捆绑的重构

### 3. 验证修复

```bash
# 运行特定的回归测试
pytest tests/test_module.py::test_regression -v

# 运行完整套件——无回归
pytest tests/ -q
```

### 4. 如果修复不起作用——三的法则

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

### 5. 如果 3+ 次修复失败：质疑架构

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

**停止并质疑基本面：**
- 这个模式从根本上合理吗？
- 我们是否"仅靠惯性坚持它"？
- 我们应该重构架构而不是继续修复症状？

**在尝试更多修复之前与用户讨论。**

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

---

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

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

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

**如果 3+ 次修复失败：** 质疑架构（阶段4 步骤5）。

## 常见合理化

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

## 快速参考

| 阶段 | 关键活动 | 成功标准 |
|-------|---------------|------------------|
| **1. 根因** | 阅读错误、复现、检查更改、收集证据、追踪数据流 | 理解什么和为什么 |
| **2. 模式** | 找到工作示例、比较、识别差异 | 知道有什么不同 |
| **3. 假设** | 形成理论、最小化测试、一次一个变量 | 确认或新假设 |
| **4. 实施** | 创建回归测试、修复根因、验证 | Bug 解决，所有测试通过 |

## Harness-agent 集成

### 调查工具

在阶段1期间使用这些工具：

- **`grep`**——在源中查找错误字符串和追踪引用
- **`glob`**——按名称或模式定位文件
- **`read_file`**——带行号读取源以进行精确分析
- **`execute`**——运行测试、检查 git 历史、复现 bug
- **`web_fetch`**——研究错误消息和库文档

### 与 `task` 一起使用

对于复杂的多组件调试，调度调查子代理：

```text
task: 调查为什么 [特定测试/行为] 失败

上下文：
遵循 systematic-debugging 技能：
1. 仔细阅读错误消息
2. 复现问题
3. 追踪数据流以找到根因
4. 报告发现——还不要修复

错误：[粘贴完整错误]
文件：[失败代码的路径]
测试命令：[确切命令]
```

### 与 test-driven-development 一起使用

修复 bug 时：
1. 编写复现 bug 的测试（红色）
2. 系统性地调试以找到根因
3. 修复根因（绿色）
4. 测试证明修复并防止回归

## 现实影响

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

**没有捷径。没有猜测。系统性总是赢。**

