Skip to content
Skills Library
Programming · Analysis

systematic-debugging

/systematic-debugging

遇到任何 Bug、测试失败或异常行为时使用,在提出修复方案之前

Licence
MIT
Last repository change
29.10.2026

Assessment and security

92/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability17 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: condition-based-waiting-example.ts, find-polluter.sh

What it does and when to use it

遇到任何 Bug、测试失败或异常行为时使用,在提出修复方案之前

Original author description

遇到任何 Bug、测试失败或异常行为时使用,在提出修复方案之前

How it works

  1. 概述
  2. 铁律
  3. 何时使用
  4. 四个阶段
  5. 危险信号——停止并遵循流程
  6. 人类伙伴发出的做错了的信号
  7. 常见合理化借口
  8. 快速参考
  9. 当流程揭示“没有根因”时
  10. 辅助技术
Original SKILL.md headings · 279 lines, 553 words
SKILL.md preview
---
name: systematic-debugging
description: 遇到任何 Bug、测试失败或异常行为时使用,在提出修复方案之前
---

# 系统化调试

## 概述

**核心原则:** 必须先找到根因,再尝试修复。只修症状就是失败。

**违反本流程的字面规定,就是违反调试的精神。**

## 铁律

```
未先调查根因,不得修复
```

未完成阶段 1,不得提出修复方案。

## 何时使用

适用于任何技术问题:
- 测试失败
- 生产环境 Bug
- 异常行为
- 性能问题
- 构建失败
- 集成问题

**尤其在以下情况必须使用:**
- 时间紧迫(紧急情况容易让人想猜)
- “就快速修一下”看起来很明显
- 你已经试过多次修复
- 之前的修复没起作用
- 你还没完全理解问题

**以下情况不要跳过:**
- 问题看起来简单(简单 Bug 也有根因)
- 你很急(赶工必然返工)
- 经理想让你立刻修好(系统化比乱撞更快)

## 四个阶段

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

### 阶段 1:根因调查

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

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

2. **稳定复现**
   - 能可靠触发吗?
   - 确切的步骤是什么?
   - 每次都发生吗?
   - 如果无法复现 → 收集更多数据,不要猜

3. **检查近期变更**
   - 什么变更可能导致此问题?
   - Git diff、近期提交
   - 新依赖、配置变更
   - 环境差异

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

   **当系统有多个组件时(CI → 构建 → 签名,API → 服务 → 数据库):**

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

   运行一次,收集证据显示在哪里断裂
   然后分析证据,定位出故障的组件
   然后调查该特定组件
   ```

   **示例(多层系统):**
   ```bash
   # 第 1 层:工作流
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"

   # 第 2 层:构建脚本
   echo "=== Env vars in build script: ==="
   printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"

   # 第 3 层:签名脚本
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # 第 4 层:实际签名
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   **这能揭示:** 哪一层失败(secrets → 工作流 ✓,工作流 → 构建 ✗)

5. **追踪数据流**

   **当错误位于调用栈深处时:**

   完整反向追踪技术见本目录下的 `root-cause-tracing.md`。

   **快速版:**
   - 错误值从哪里产生?
   - 谁用错误值调用了这里?
   - 持续向上追踪直到找到源头
   - 在源头修复,而非症状处

### 阶段 2:模式分析

**修复前先找到模式:**

1. **找到可工作的示例**
   - 在同一代码库中定位类似的可用代码
   - 有什么可工作的代码与出问题的代码相似?

2. **与参考实现对比**
   - 如果实现某个模式,完整阅读参考实现
   - 不要略读——逐行阅读
   - 完全理解模式后再应用

3. **找出差异**
   - 可用与不可用之间有什么不同?
   - 列出每一处差异,无论多小
   - 不要假设“那不可能有影响”

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

### 阶段 3:假设与验证

**科学方法:**

1. **形成单一假设**
   - 明确陈述:“我认为 X 是根因,因为 Y”
   - 写下来
   - 要具体,不要含糊

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

3. **验证后再继续**
   - 有效吗?有效 → 阶段 4
   - 无效?形成新假设
   - 不要在已有修复上叠加更多修复

4. **当你不知道时**
   - 说“我不理解 X”
   - 不要假装知道
   - 寻求帮助
   - 进一步研究

### 阶段 4:实施

**修复根因,而非症状:**

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

2. **实施单一修复**
   - 针对已识别的根因
   - 一次一个变更
   - 不做“顺便改一下”的改进
   - 不捆绑重构

3. **验证修复**
   - 测试现在通过了吗?
   - 其他测试没被破坏吗?
   - 问题真的解决了吗?
   - 声称成功前使用 `superpowers:verification-before-completion` 技能

4. **如果修复无效**
   - 停止
   - 计数:你试了几次修复?
   - 如果 < 3:回到阶段 1,用新信息重新分析
   - **如果 ≥ 3:停止并质疑架构(见下方第 5 步)**
   - 未经架构讨论,不要尝试第 4 次修复

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

   **表明架构问题的模式:**
   - 每次修复都在不同地方暴露新的共享状态/耦合/问题
   - 修复需要“大规模重构”才能实施
   - 每次修复都在别处产生新症状

   **停止并质疑根本假设:**
   - 这个模式从根本上合理吗?
   - 我们是不是“纯粹出于惯性在坚持”?
   - 应该重构架构还是继续修症状?

   **在尝试更多修复之前与人类伙伴讨论**

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

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

如果你发现自己想:
- “先快速修一下,之后再调查”
- “就试试改 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`**——用条件轮询替代任意超时
Files in this package (11)
  • CREATION-LOG.md 4 KB
  • SKILL.md 9 KB
  • condition-based-waiting-example.ts 5 KB
  • condition-based-waiting.md 3 KB
  • defense-in-depth.md 3 KB
  • find-polluter.sh 2 KB
  • root-cause-tracing.md 5 KB
  • test-academic.md 1 KB
  • test-pressure-1.md 2 KB
  • test-pressure-2.md 2 KB
  • test-pressure-3.md 3 KB

Versions

RepositoryScoreLicence
This page · yangshun2005/superpowers-cn92MIT
magnus919/agent-skills100MIT
FrancoStino/opencode-skills-collection100MIT
foryourhealth111-pixel/Vibe-Skills100Apache-2.0
GanyuanRan/Aegis100MIT
rootcastleco/rei-skills100MIT
jkaloger/lazyspec100MIT
innei/ryugi100MIT
yusixian/anjian100MIT

Database snapshot: 13.11.2026 · package version 755523e3a6c8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sr-systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100ferrox-systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
  • 100debugging
    根据证据定位未知根因并验证修复。 Use when: bug、测试失败或异常行为的根因尚未查明。 Not for: 新功能设计、已确定原因且有精准失败检查的修复(用 tdd)。 Output: 有依据的诊断与修复验证;未解决时给出真实缺口和下一步。
  • 100debug
    Use when investigating bugs, errors, failing tests, or unexpected behavior. Enforces systematic root-cause investigation BEFORE attempting any fix. Invoke this skill before writing any fix code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.