系統調試

概述

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

核心原則： 在嘗試修復之前始終找到根本原因。症狀修復失敗。

**違反此過程的字面意思就是違反調試精神。 **

鐵律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果您尚未完成第一階段，則無法提出修復建議。

何時使用

用於任何技術問題：

測試失敗
生產中的錯誤
意外行為
性能問題
構建失敗
整合問題

特別是在以下情況下使用此功能：

在時間壓力下（緊急情況讓人很容易猜測）
「只需一個快速解決方案」似乎是顯而易見的
您已經嘗試過多次修復
之前的修復不起作用
你沒有完全理解這個問題

在以下情況下不要跳過：

問題看起來很簡單（簡單的錯誤也有根本原因）
你很著急（著急保證返工）
經理希望立即修復（系統化比混亂更快）

四個階段

您必須先完成每個階段，然後才能進入下一階段。

第一階段：根本原因調查

嘗試任何修復之前：

仔細閱讀錯誤訊息
- 不要跳過過去的錯誤或警告
- 它們通常包含精確的解決方案
- 完整讀取堆疊追蹤
- 記下行號、檔案路徑、錯誤程式碼
一致地再現
- 你能可靠地觸發它嗎？
- 具體步驟是什麼？
- 每次都會發生嗎？
- 如果不可重現→收集更多數據，不要猜測
檢查最近的變更
- 是什麼變化可能導致這種情況？
- Git diff，最近的提交
- 新的依賴項，配置更改
- 環境差異
收集多組件系統中的證據

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

在提出修復建議之前，添加診斷工具：

For EACH component boundary:
  - Log what data enters component
  - Log what data exits component
  - Verify environment/config propagation
  - Check state at each layer

Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component

示例（多層系統）：

# 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"

**這揭示了：**哪一層失敗了（祕密→工作流程✓，工作流程→建構✗）

追蹤資料流

當錯誤深入呼叫堆疊時：

看root-cause-tracing.md在此目錄中瞭解完整的向後跟蹤技術。

快速版本：

不良價值從何而來？
什麼叫這個價值不高？
繼續追蹤，直到找到源頭
從根源解決，而不是從症狀解決

第二階段：模式分析

修復前先找到圖案：

尋找工作範例
- 在同一代碼庫中找到相似的工作代碼
- 有什麼作品與已損壞的作品相似？
與參考文獻比較
- 如果實現模式，請完整閱讀參考實現
- 不要略讀 - 閱讀每一行
- 應用前充分了解模式
找出差異
- 工作和壞掉有什麼不同？
- 列出每一個差異，無論多麼小
- 不要認為“那不重要”
瞭解依賴關係
- 這還需要什麼其他組件？
- 什麼設置、配置、環境？
- 它做出了什麼假設？

第三階段：假設和測試

科學方法：

形成單一假設
- 明確說明：“我認為 X 是根本原因，因為 Y”
- 寫下來
- 要具體，不要含糊
最少測試
- 做出盡可能小的改變來檢驗假設
- 一次一個變量
- 不要一次修復多個問題
繼續之前先驗證
- 有效嗎？是 → 第 4 階段
- 沒起作用？形成新的假設
- 不要在頂部添加更多修復
當你不知道時
- 說“我不明白X”
- 別假裝知道
- 求人
- 研究更多

第四階段：實施

解決根本原因，而不是症狀：

建立失敗的測試用例
- 最簡單的再現
- 如果可能的話進行自動化測試
- 如果沒有框架，一次性測試腳本
- 修復前必須有
- 使用superpowers:test-driven-development編寫正確的失敗測試的技能
實施單一修復
- 解決已確定的根本原因
- 一次更改一個
- 沒有“當我在這裡”的改進
- 沒有捆綁重構
驗證修復
- 現在測試通過了嗎？
- 其他測試沒有被破壞嗎？
- 問題真的解決了嗎？
如果修復不起作用
- 停止
- 數數：您嘗試過多少次修復？
- 如果 < 3：返回階段 1，用新信息重新分析
- 如果 ≥ 3：停止並質疑架構（下面的步驟 5）
- 在沒有進行架構討論的情況下，不要嘗試修復 #4
如果 3 個以上修復失敗：架構問題

指示架構問題的模式：

每個修復都會在不同位置揭示新的共享狀態/耦合/問題
修復需要“大規模重構”才能實施
每次修復都會在其他地方產生新的症狀

停下來詢問基本原理：

這種模式從根本上來說合理嗎？
我們是“純粹因為慣性而堅持下去”嗎？
我們應該重構架構還是繼續修復症狀？

在嘗試更多修復之前與您的人類合作夥伴討論

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

危險信號 - 停止並遵循流程

如果你發現自己在想：

“現在快速修復，稍後再調查”
“嘗試改變X看看是否有效”
“添加多個更改，運行測試”
“跳過測試，我手動驗證”
“可能是X，讓我解決這個問題”
“我不完全明白，但這可能有用”
“模式說X，但我會以不同的方式對其進行調整”
“以下是主要問題：[列出未經調查的修復]”
在追蹤資料流之前提出解決方案
「再嘗試一次修復」（當已嘗試 2+ 次）
每次修復都會在不同的地方揭示新問題

**所有這些都意味著：停止。返回第一階段。 **

如果 3 個以上修復失敗： 質疑架構（請參閱階段4.5）

你的人類伴侶發出的信號表明你做錯了

注意這些重定向：

“那不是發生了嗎？” - 你假設沒有驗證
「它會告訴我們…嗎？」 - 你應該增加證據收集
「停止猜測」——你在不理解的情況下提出修復方案
「Ultrathink this」－質疑基本面，而不僅僅是症狀
「我們被困住了？」（沮喪）- 你的方法不起作用

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

常見的合理化理由

對不起	現實
「問題很簡單，不需要流程」	簡單的問題也有根本原因。對於簡單的錯誤，處理速度很快。
「緊急情況，沒有時間處理」	系統調試比猜測和檢查顛簸更快。
“先嘗試一下，然後再調查”	第一個修復設置了模式。從一開始就做對。
“確認修復有效後我將編寫測試”	未經測試的修復不會持續下去。首先測試證明這一點。
“一次進行多個修復可以節省時間”	無法隔離有效的方法。導致新的錯誤。
“參考資料太長，我會調整模式”	部分理解一定會出現錯誤。完整地閱讀它。
“我看到問題了，讓我解決它”	看到症狀≠瞭解根本原因。
「再嘗試一次修復」（兩次以上失敗後）	3+次失敗=架構問題。問題模式，不要再修復。

快速參考

相	主要活動	成功標準
1.根本原因	讀取錯誤、重現、檢查更改、收集證據	瞭解什麼和為什麼
2.圖案	查找工作示例，進行比較	找出差異
3.假設	形成理論，最少測試	證實的或新的假設
4.實施	創建測試、修復、驗證	錯誤已解決，測試通過

當流程顯示“沒有根本原因”時

如果系統調查顯示問題確實是環境性的、時間相關的或外部的：

您已完成該過程
記錄您調查的內容
實施適當的處理（重試、超時、錯誤消息）
添加監控/日誌記錄以供將來調查

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

配套技術

這些技術是系統調試的一部分，可以在此目錄中找到：

root-cause-tracing.md - 透過呼叫堆疊向後追蹤錯誤以找到原始觸發器
defense-in-depth.md - 在找到根本原因後添加多層驗證
condition-based-waiting.md - 用條件輪詢替換任意逾時

相關技能：

superpowers:test-driven-development - 用於建立失敗的測試案例（第4階段，第1步）
超級能力：完成前驗證 - 在聲明成功之前驗證修復是否有效

現實世界的影響

從調試會話：

系統方法：15-30 分鐘修復
隨機修復方法：2-3小時的顛簸
首次修復率：95% vs 40%
引入新錯誤：接近零與常見

systematic-debugging