# Systematic Debugging

> 4 階段系統化除錯方法論，具備根本原因分析和基於證據的驗證。用於除錯複雜問題。

- Skill: `tai-ch0802/systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tai-ch0802/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tai-ch0802/systematic-debugging/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Tai-ch0802 (https://skillmd.com/u/tai-ch0802)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/tai-ch0802/systematic-debugging

---


# 系統化除錯

> 來源：obra/superpowers

## 概覽
此技能提供結構化的除錯方法，防止隨機猜測並確保在解決問題前正確理解問題。

## 4 階段除錯流程

### 階段 1：重現
修復前，可靠地重現問題。

```markdown
## 重現步驟
1. [重現的確切步驟]
2. [下一步驟]
3. [預期 vs 實際結果]

## 重現率
- [ ] 始終（100%）
- [ ] 經常（50-90%）
- [ ] 有時（10-50%）
- [ ] 罕見（<10%）
```

### 階段 2：隔離
縮小範圍。

```markdown
## 隔離問題
- 這是什麼時候開始的？
- 最近有什麼改變？
- 在所有環境都會發生嗎？
- 能用最少的程式碼重現嗎？
- 觸發它的最小變更是什麼？
```

### 階段 3：理解
找到根本原因，而非僅是症狀。

```markdown
## 根本原因分析
### 5 個為什麼
1. 為什麼：[第一個觀察]
2. 為什麼：[更深的原因]
3. 為什麼：[再更深]
4. 為什麼：[越來越近]
5. 為什麼：[根本原因]
```

### 階段 4：修復與驗證
修復並驗證它真的被修復了。

```markdown
## 修復驗證
- [ ] Bug 不再可重現
- [ ] 相關功能仍然正常
- [ ] 沒有引入新問題
- [ ] 已新增測試防止回歸
```

## 除錯檢查清單

```markdown
## 開始前
- [ ] 能一致地重現
- [ ] 有最小重現案例
- [ ] 理解預期行為

## 調查期間
- [ ] 檢查最近的變更（git log）
- [ ] 檢查日誌錯誤
- [ ] 需要時增加日誌
- [ ] 使用除錯器/中斷點

## 修復後
- [ ] 根本原因已記錄
- [ ] 修復已驗證
- [ ] 已新增回歸測試
- [ ] 已檢查類似程式碼
```

## 常用除錯指令

```bash
# 最近的變更
git log --oneline -20
git diff HEAD~5

# 搜尋模式
grep -r "errorPattern" --include="*.ts"

# 檢查日誌
pm2 logs app-name --err --lines 100
```

## 反模式

❌ **隨機修改** — 「也許改這個就好了......」
❌ **忽略證據** — 「那不可能是原因」
❌ **假設** — 「一定是 X」但沒有證據
❌ **不先重現** — 盲目修復
❌ **停在症狀** — 沒找到根本原因