Programming · Analysis
systematic-debugging
/systematic-debugging
遇到任何 Bug、测试失败或异常行为时使用,在提出修复方案之前
For whom
- Author
- yangshun2005 ↗
- Repository
- superpowers-cn ↗
- 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
- 概述
- 铁律
- 何时使用
- 四个阶段
- 危险信号——停止并遵循流程
- 人类伙伴发出的做错了的信号
- 常见合理化借口
- 快速参考
- 当流程揭示“没有根因”时
- 辅助技术
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
| Repository | Score | Licence |
|---|---|---|
| This page · yangshun2005/superpowers-cn | 92 | MIT |
| magnus919/agent-skills | 100 | MIT |
| FrancoStino/opencode-skills-collection | 100 | MIT |
| foryourhealth111-pixel/Vibe-Skills | 100 | Apache-2.0 |
| GanyuanRan/Aegis | 100 | MIT |
| rootcastleco/rei-skills | 100 | MIT |
| jkaloger/lazyspec | 100 | MIT |
| innei/ryugi | 100 | MIT |
| yusixian/anjian | 100 | MIT |
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.