laitszkin/systematic-debug

技能目標

以流程化方式重現非預期行為。 修復後建立回歸測試，避免再次出現。

驗收條件

• 非預期行為被修復。
• 相關回歸測試被建立。
• 根因已確認，不只修了症狀。

工作流程

0. 錯誤分類

開始除錯前，先分類錯誤類型，選擇對應策略：

| 類型 | 特徵 | 適用方法 | |------|------|----------| | 語法/型別錯誤 | 編譯器或 linter 直接指出 | 直接修復錯誤訊息指出的位置 | | 邏輯錯誤 | 輸出結果錯誤、測試失敗 | 假設驅動除錯 + 二元搜尋 | | 狀態錯誤 | 間歇性、順序相依 | 追蹤狀態轉移、找出變異點 | | 整合錯誤 | 獨立運作正常、連接後失敗 | 檢查邊界、合約、格式 | | 環境錯誤 | 部分環境正常、部分異常 | 比對環境差異、檢查設定檔 | | 效能錯誤 | 結果正確但緩慢/耗資源 | 效能分析工具、找熱點、檢查複雜度 |

1. 分析問題

按照用戶給出的資訊閱讀相關代碼。 排查可能導致問題的原因。從錯誤訊息、最近變更、日誌中收集證據。

選擇適合當前問題的除錯方法（參考下方方法指引），形成可證偽的假設。

2. 重現問題

整理所有可能導致問題的原因，撰寫測試案例嘗試重現該問題。 若所有構思的可能性均無法重現非預期行為，需重新假設直至測試有效重現。

一次只改變一個變數。若同時改變多個條件，無法歸因因果關係。

3. 修復代碼

對代碼進行修復，直至重現測試全數通過。

修復根因而非症狀。修復完成後，保留重現測試作為回歸測試。

除錯方法選擇指引

根據問題類型選擇最適合的方法：

假設驅動除錯（Hypothesis-Driven Debugging）

適用於線上事故、邏輯錯誤。按 cheapest-first 順序測試假設。

1. 形成可證偽的假設：「我認為 X 是根因，因為 Y」
2. 預測：「若假設正確，我會觀察到 Z」
3. 測試：以最小變更驗證預測
4. 收斂：預測吻合 → 找到原因；不吻合 → 新假設 參考：Google SRE、Zeller's "Why Programs Fail"

Five Whys

適用於簡單、線性的失敗。反覆追問「為什麼」，沿著單一因果鏈追溯。 注意：當多個原因互動時，Five Whys 會遺漏分支原因。

Fault Tree Analysis（FTA）

適用於多因互動、架構層級的預防。從頂層失敗出發，自上而下分解所有可能的貢獻原因， 直到可觀測、可測試的葉節點。找出最小 cut sets（單點故障優先處理）。 參考：NASA SW 手冊、Chaos Engineering

Kepner-Tregoe IS / IS NOT

適用於多團隊、跨服務的複雜問題。透過四維度矩陣強制結構化：

| 維度 | IS（問題在哪） | IS NOT（問題不在哪） | 差異（原因所在） | |------|---------------|-------------------|----------------| | What | | | | | Where | | | | | When | | | | | Extent | | | |

有效的根因必須解釋所有 IS 和所有 IS NOT。KT 最適合環境穩定、邊界清晰的問題，不適合串聯式災難。 參考：Kepner-Tregoe Problem Solving

方法選擇原則：當有多個可能根因時，先從 cheapest-first 開始測試（最簡單驗證的假設優先）。

防禦機制

Red Flags — 立即停止並回到分析階段

若發現自己有以下想法，表示正在跳過調查步驟，需立即停止：

• 「先快速修一下，有空再調查」
• 「試試改 X 看會不會好」
• 「一次改多處，跑測試看看」
• 「跳過測試，我手動驗證就好」
• 「大概是 X 的問題，直接修吧」
• 「我不完全理解但這樣應該可以」
• 「主要的問題是：[列出修復方案，沒有調查過程]」
• 「再試一次就好」（已經試過 2+ 次）

以上任何一個出現 → 停止修復，返回步驟 1。

Rule of Three — 架構質疑機制

若同一錯誤經過 3 次修復仍失敗：

1. 停止 — 不要嘗試第 4 次修復
2. 回顧：已嘗試了哪些修復？失敗模式是什麼？
3. 質疑：是否當前的架構假設有問題？是否在錯誤的抽象層進行修復？
4. 升級：向用戶提交調查報告，包含已排除的假設與建議的架構調整
5. 在獲得用戶決策前，不繼續迭代

假設分類帳

在除錯過程中記錄每個假設的狀態：

假設：[對根因的推測]
狀態：[未驗證 / 已確認 / 已推翻]
驗證方式：[做了什麼檢查]
證據：[觀察到的結果]

每次形成新假設時，先確認它是否能解釋所有已觀測到的症狀。

找不到根因的處理

若系統性調查後仍無法找到根因（環境性、時序性、外部依賴問題）：

1. 承認已完整執行了調查流程
2. 記錄已調查了哪些方向
3. 實施適當的防護措施（retry、timeout、錯誤訊息改善）
4. 加入監控或日誌，以便未來有更多證據時再次調查

95% 的「找不到根因」其實是調查不夠深。在放棄前確認已用盡當前可用的證據。

範例

• "結帳頁面有時會出現 500 錯誤" → "排查 coupon 驗證、定價計算、外部折扣服務。撰寫重現測試，確認根因後修復，保留回歸測試。"