---
source: ../../../core/systematic-debugging.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-03-24
status: current
---

# 系統化除錯工作流程

> **語言**: [English](../../../core/systematic-debugging.md) | 繁體中文

**版本**: 1.0.0
**最後更新**: 2026-03-20
**適用性**: 所有使用 AI 輔助開發的軟體專案
**範圍**: 通用 (Universal)
**靈感來源**: [Superpowers](https://github.com/obra/superpowers) — systematic-debugging (MIT)

---

## 目的

定義結構化的四階段除錯工作流，防止常見的「猜測修復」反模式。強制要求在嘗試修復前先進行根因分析，並包含 **3-Strike Rule** 以提早發現架構問題。

---

## 術語表

| 術語 | 定義 |
|------|------|
| 根因 (Root Cause) | 缺陷存在的根本原因，而非僅僅是表徵 |
| 3-Strike Rule | 連續 3 次修復嘗試失敗後，懷疑存在架構問題 |
| 反向追蹤 (Backward Tracing) | 從錯誤表徵追溯到源頭 |
| 元件邊界 (Component Boundary) | 兩個模組或子系統之間的介面 |

---

## 核心原則 — 鐵律

> **禁止跳過根因分析直接修復。**

如果你發現自己在說「快速修復」、「試試看」或「應該可以了」— **停下來**，回到第一階段。

---

## 四階段除錯工作流

### 階段 1：觀察與重現

| 步驟 | 說明 |
|------|------|
| 收集錯誤資訊 | 錯誤訊息、堆疊追蹤、日誌 |
| 確定重現步驟 | 建立可靠的重現路徑 |
| 記錄環境條件 | 作業系統、版本、設定 |

### 階段 2：根因分析

| 技術 | 適用場景 |
|------|----------|
| 反向追蹤 | 從錯誤點向後追溯資料流 |
| 二分法 | 快速縮小問題範圍 |
| 元件隔離 | 逐一排除元件 |
| 日誌分析 | 檢查事件順序和狀態變化 |

### 階段 3：修復

| 規則 | 說明 |
|------|------|
| 先寫測試 | 寫一個重現 bug 的失敗測試 |
| 最小化修改 | 只修改必要的程式碼 |
| 驗證修復 | 確認測試從紅轉綠 |
| 無副作用 | 確認沒有引入新的 bug |

### 階段 4：驗證與預防

| 步驟 | 說明 |
|------|------|
| 執行完整測試套件 | 確保沒有回歸 |
| 更新文件 | 記錄根因和修復方案 |
| 回顧 | 是否需要加強預防措施 |

## 3-Strike Rule

連續 3 次修復嘗試失敗時：

1. **停止修復** — 不要再嘗試第 4 次
2. **升級** — 通知架構師或資深開發人員
3. **重新分析** — 從更高層次重新分析問題
4. **考慮重構** — 問題可能在架構層面

## 相關標準

- [驗證證據](verification-evidence.md)
- [測試標準](testing-standards.md)
- [AI 模型選擇策略](model-selection.md)
