系統化除錯

概述

隨機修復浪費時間並產生新錯誤。快速修補掩蓋根本問題。

核心原則： 在嘗試修復前，務必先找出根本原因。症狀修復就是失敗。

違反此流程的文字，就是違反除錯的精神。

鐵律

未經根本原因調查，不得進行修復

如果你尚未完成第一階段，就不能提出修復方案。

使用時機

適用於任何技術問題：

測試失敗
生產環境的錯誤
非預期行為
效能問題
建置失敗
整合問題

特別需要使用的時機：

時間壓力下（緊急狀況容易讓人想猜測）
「只快速修一下」看似很明顯
你已經嘗試過多次修復
之前的修復沒有效果
你尚未完全理解問題

不應跳過的時機：

問題看似簡單（簡單的錯誤也有根本原因）
你很趕時間（匆忙保證會需要重做）
主管要求立刻修好（系統化比亂試更快）

四個階段

你必須完成每個階段後才能進入下一個。

第一階段：根本原因調查

在嘗試任何修復之前：

仔細閱讀錯誤訊息
- 不要跳過錯誤或警告
- 它們通常包含確切的解決方案
- 完整閱讀堆疊追蹤
- 記下行號、檔案路徑、錯誤碼
穩定重現問題
- 你能可靠地觸發它嗎？
- 確切的步驟是什麼？
- 每次都會發生嗎？
- 如果無法重現 → 收集更多資料，不要猜測
檢查最近的變更
- 什麼變更可能導致這個問題？
- Git diff、最近的提交
- 新的相依套件、設定變更
- 環境差異

在多元件系統中收集證據

當系統有多個元件（CI → 建置 → 簽署，API → 服務 → 資料庫）：

在提出修復前，加入診斷工具：

針對每個元件邊界：
  - 記錄進入元件的資料
  - 記錄離開元件的資料
  - 驗證環境/設定傳遞
  - 檢查每一層的狀態

執行一次以收集證據，顯示問題在哪裡中斷
然後分析證據以找出故障元件
然後調查該特定元件

範例（多層系統）：

# 第一層：工作流程
echo "=== 工作流程中可用的機密： ==="
echo "IDENTITY: ${IDENTITY:+已設定}${IDENTITY:-未設定}"

# 第二層：建置腳本
echo "=== 建置腳本中的環境變數： ==="
env | grep IDENTITY || echo "IDENTITY 不在環境中"

# 第三層：簽署腳本
echo "=== 鑰匙圈狀態： ==="
security list-keychains
security find-identity -v

# 第四層：實際簽署
codesign --sign "$IDENTITY" --verbose=4 "$APP"

這會顯示： 哪一層失敗（機密 → 工作流程 ✓，工作流程 → 建置 ✗）

追蹤資料流

當錯誤在呼叫堆疊深處時：

請參閱此目錄中的 root-cause-tracing.md 以了解完整的反向追蹤技術。

快速版本：
- 錯誤值從哪裡產生？
- 誰用錯誤值呼叫了這個？
- 持續向上追蹤直到找到源頭
- 在源頭修復，而不是在症狀處

第二階段：模式分析

在修復前找出模式：

尋找運作中的範例
- 在同一個程式碼庫中找到類似的運作中程式碼
- 什麼運作中的東西與壞掉的類似？
與參考資料比較
- 如果正在實作某個模式，完整閱讀參考實作
- 不要略讀——閱讀每一行
- 在應用前完全理解該模式
找出差異
- 運作中與壞掉的有什麼不同？
- 列出每一個差異，無論多小
- 不要假設「那個沒關係」
了解相依性
- 這個需要哪些其他元件？
- 哪些設定、配置、環境？
- 它做了哪些假設？

第三階段：假設與測試

科學方法：

形成單一假設
- 清楚陳述：「我認為 X 是根本原因，因為 Y」
- 寫下來
- 要具體，不要模糊
最小化測試
- 做最小的變更來測試假設
- 一次只改變一個變數
- 不要同時修復多個問題
繼續前先驗證
- 成功了嗎？是 → 第四階段
- 沒成功？形成新的假設
- 不要在之上再加更多修復
當你不知道時
- 說「我不理解 X」
- 不要假裝知道
- 尋求幫助
- 做更多研究

第四階段：實作

修復根本原因，而不是症狀：

建立會失敗的測試案例
- 最簡單的重現方式
- 盡可能自動化測試
- 如果沒有測試框架，用一次性測試腳本
- 必須在修復前完成
- 使用 superpowers:test-driven-development 技能來撰寫適當的失敗測試
實作單一修復
- 處理已識別的根本原因
- 一次只做一個變更
- 不要「順便」做改進
- 不要捆綁重構
驗證修復
- 測試現在通過了嗎？
- 其他測試沒有被破壞？
- 問題確實解決了嗎？
如果修復無效
- 停止
- 計算：你已經嘗試了幾次修復？
- 如果 < 3：回到第一階段，用新資訊重新分析
- 如果 ≥ 3：停止並質疑架構（下面的步驟 5）
- 不要在沒有架構討論的情況下嘗試第四次修復
如果 3 次以上修復失敗：質疑架構

表示架構問題的模式：
- 每次修復都在不同地方揭露新的共享狀態/耦合/問題
- 修復需要「大規模重構」才能實作
- 每次修復都在其他地方產生新症狀
停止並質疑基本問題：
- 這個模式從根本上合理嗎？
- 我們只是因為慣性而堅持嗎？
- 我們應該重構架構，還是繼續修復症狀？
在嘗試更多修復前，與你的人類夥伴討論

這不是失敗的假設——這是錯誤的架構。

紅旗——停止並遵循流程

如果你發現自己在想：

「先快速修一下，之後再調查」
「先試著改 X，看看會不會好」
「一次改多個，然後跑測試」
「跳過測試，我手動驗證」
「大概是 X 的問題，我來修」
「我不完全理解，但這樣可能有效」
「模式說 X，但我會用不同方式調整」
「主要問題是：[列出修復方案，沒有調查]」
在追蹤資料流之前就提出解決方案
「再試一次修復」（已經嘗試 2 次以上）
每次修復都在不同地方揭露新問題

以上所有情況都代表：停止。回到第一階段。

如果 3 次以上修復失敗： 質疑架構（見第四階段第 5 點）

你的人類夥伴表示你做錯的信號

注意這些引導：

「那不是發生了嗎？」——你未經驗證就假設
「它會顯示給我們……？」——你應該加入證據收集
「別再猜了」——你在沒有理解的情況下提出修復
「用 Ultrathink 思考這個」——質疑基本問題，而不只是症狀
「我們卡住了？」（沮喪）——你的方法沒有效

當你看到這些時： 停止。回到第一階段。

常見的合理化藉口

藉口	現實
「問題很簡單，不需要流程」	簡單的問題也有根本原因。流程對簡單的錯誤也很快。
「緊急狀況，沒時間走流程」	系統化除錯比亂猜亂試更快。
「先試這個，之後再調查」	第一次修復就定了模式。從一開始就做對。
「確認修復有效後再寫測試」	未經測試的修復無法持久。先測試才能證明。
「一次做多個修復節省時間」	無法隔離哪個有效。還會產生新錯誤。
「參考資料太長，我調整一下模式」	部分理解保證會產生錯誤。完整閱讀它。
「我看到問題了，讓我修」	看到症狀 ≠ 理解根本原因。
「再試一次修復」（2 次以上失敗後）	3 次以上失敗 = 架構問題。質疑模式，不要繼續修。

快速參考

階段	主要活動	成功標準
1. 根本原因	閱讀錯誤、重現、檢查變更、收集證據	理解「什麼」和「為什麼」
2. 模式	尋找運作中範例、比較	找出差異
3. 假設	形成理論、最小化測試	確認或新假設
4. 實作	建立測試、修復、驗證	錯誤解決、測試通過

當流程顯示「無根本原因」時

如果系統化調查顯示問題確實是環境、時間依賴或外部因素：

你已完成流程
記錄你調查的內容
實作適當的處理（重試、逾時、錯誤訊息）
加入監控/記錄以供未來調查

但是： 95% 的「無根本原因」案例都是調查不完整。

輔助技術

這些技術是系統化除錯的一部分，可在本目錄中找到：

root-cause-tracing.md - 透過呼叫堆疊反向追蹤錯誤，找出原始觸發點
defense-in-depth.md - 在找到根本原因後，於多層加入驗證
condition-based-waiting.md - 用條件輪詢取代任意逾時

相關技能：

superpowers:test-driven-development - 用於建立會失敗的測試案例（第四階段，步驟 1）
superpowers:verification-before-completion - 在聲稱成功前驗證修復有效

實際影響

來自除錯會議的資料：

系統化方法：15-30 分鐘修復
隨機修復方法：2-3 小時亂試
首次修復成功率：95% 對比 40%
引入新錯誤：接近零對比常見

systematic-debugging

相關技能