# Systematic Debugging

> 遇到任何 bug、测试失败或异常行为时使用，在提议修复之前

- **Type:** Skill
- **Install:** `agentstack add skill-myswallow-superpowers-lite-systematic-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [MySwallow](https://agentstack.voostack.com/s/myswallow)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [MySwallow](https://github.com/MySwallow)
- **Source:** https://github.com/MySwallow/superpowers-lite/tree/main/skills/systematic-debugging

## Install

```sh
agentstack add skill-myswallow-superpowers-lite-systematic-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 系统化调试

## 概述

随意修复浪费时间，并制造新 bug。快速补丁掩盖底层问题。

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

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

## 铁律

```
没有根因调查就不要谈修复
```

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

## 何时使用

适用于**任何**技术问题：
- 测试失败
- 生产 bug
- 异常行为
- 性能问题
- 构建失败
- 集成问题

**尤其在这些情况下使用：**
- 时间压力大（紧急情况下容易诱使你猜测）
- "就这一处快修一下" 看起来显而易见
- 你已经试过多次修复
- 之前的修复无效
- 你并不完全理解问题

**不要在以下情况下跳过：**
- 问题看似简单（简单 bug 也有根因）
- 你在赶时间（赶时间一定要返工）
- 经理要求"现在就修"（系统化比乱撞更快）

## 四个阶段

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

### 阶段 1：根因调查

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

1. **仔细阅读错误信息**
   - 不要跳过错误或警告
   - 它们经常含有确切答案
   - 完整阅读 stack trace
   - 记下行号、文件路径、错误码

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

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

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

   **当系统有多个组件时（CI → build → 签名，API → service → 数据库）：**

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

   跑一次以收集证据，找出在哪儿断
   然后分析证据，识别失败的组件
   然后调查那个具体组件
   ```

   **示例（多层系统）：**
   ```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. **找出差异**
   - 工作的 vs 坏的之间有什么不同？
   - 列出每一处差异，再小也列
   - 不要假设"这不可能要紧"

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

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

**科学方法：**

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

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

3. **继续前先验证**
   - 有效？是 → 阶段 4
   - 无效？形成**新**假设
   - 不要在上面继续叠加修复

4. **当你不知道时**
   - 说 "I don't understand X"
   - 不要假装知道
   - 求助
   - 多研究

### 阶段 4：实施

**修根因，不修症状：**

1. **建立可靠的复现步骤**
   - 最简化的复现路径
   - 默认：可手动复现的清晰步骤，或一次性脚本
   - **仅当**任务/项目明确要求测试覆盖时，才写自动化测试（先红后绿）
   - 修复**前**必须能稳定复现

2. **实施单一修复**
   - 解决识别出的根因
   - 一次只改一处
   - 不要"顺手"改其他
   - 不要捆绑重构

3. **验证修复**
   - 复现步骤现在不再触发问题？
   - 跑项目已有的静态检查（类型检查 / lint / 构建），未引入新错误？
   - 如有自动化测试，相关测试通过且未破坏其他？

4. **如果修复无效**
   - 停下
   - 数一数：你试过多少次修复？
   - 若 < 3：回到阶段 1，用新信息重新分析
   - **若 ≥ 3：停下并质疑架构（下文步骤 5）**
   - 不要在无架构讨论的情况下尝试第 4 次修复

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

   **指向架构问题的模式：**
   - 每次修复都在不同地方暴露新的共享状态/耦合/问题
   - 修复要求"大规模重构"才能实现
   - 每次修复都在别处产生新症状

   **停下并质疑根本：**
   - 这个模式根本上合理吗？
   - 我们是不是"靠惯性硬撑"？
   - 应不应该重构架构而非继续修症状？

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

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

## 红色信号 - 停下并遵循流程

如果你抓到自己在想：
- "先快修一下，回头调查"
- "试着改 X 看看行不行"
- "加多个变更，看结果"
- "懒得复现，我猜一下就改"
- "应该是 X，让我修了它"
- "我没完全理解但这可能行"
- "模式说 X，但我改一下用"
- "这是主要问题：[未经调查就列修复]"
- 在追踪数据流之前提出解决方案
- **"再试一次"（已经试过 2 次以上）**
- **每次修复都在别处暴露新问题**

**以上**所有**都意味着：停下，回到阶段 1。**

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

## 你的协作伙伴提示你"方法错了"的信号

**留意这些重定向：**
- "Is that not happening?" - 你没验证就假设了
- "Will it show us...?" - 你本应加证据收集
- "Stop guessing" - 你没理解就提议修复
- "Ultrathink this" - 质疑根本，而非只看症状
- "We're stuck?"（沮丧地） - 你的方法不奏效

**当你看到这些：** 停下。回到阶段 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`** - 用条件轮询替换任意 timeout

## 真实世界影响

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MySwallow](https://github.com/MySwallow)
- **Source:** [MySwallow/superpowers-lite](https://github.com/MySwallow/superpowers-lite)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-myswallow-superpowers-lite-systematic-debugging
- Seller: https://agentstack.voostack.com/s/myswallow
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.