systematic-debugging

systematic-debugging skill 概覽

systematic-debugging skill 是一套有結構的除錯工作流程，適合想減少猜測式修補、加快找出根因的代理與開發者。它的核心原則很簡單：先調查，再改程式。也因此，它特別適合用在測試失敗、偶發不穩定行為、正式環境 bug、建置問題，以及那種「快速修一下」反而很容易把真正問題蓋掉的整合類故障。

這個 systematic-debugging skill 最適合誰

如果你有以下情況，適合用 systematic-debugging：

• 修了好幾次還是沒修好，或只能修到一半
• 在時間壓力下除錯
• 需要 AI 助手先慢下來做調查，而不是直接修表面症狀
• 想要一套可重複使用的流程來處理 bug、flaky tests 與非預期行為

特別是當問題看起來很明顯，但你其實還不知道它「為什麼會發生」時，這個 skill 很有用。

這個 skill 實際上幫你完成什麼工作

真正要完成的工作，不是「產出一個修補」。而是：

1. 重現問題
2. 追出原因
3. 一次驗證一種解釋
4. 最後才實作有針對性的修正

聽起來比較慢，但通常能明顯減少重工、失敗修補，以及因為瞎猜而引入的新 bug。

systematic-debugging 有什麼不同

一般的提示通常會從症狀直接跳到解法。systematic-debugging skill 明確反對這種做法。這個 repo 強調一種近乎「鐵律」的流程：在完成根因調查之前，不要先提修法。

周邊檔案也讓它比一般除錯清單更實用：

• root-cause-tracing.md：當你看到的錯誤離真正來源很遠時很有幫助
• condition-based-waiting.md：適合處理因為任意延遲而造成的 flaky async tests
• defense-in-depth.md：幫你把一次性的驗證修補，提升成更有結構的預防機制
• find-polluter.sh：用來隔離會洩漏檔案或狀態的測試

最適合的問題類型

systematic-debugging for Debugging 特別適合以下情況：

• 測試失敗，但你還無法解釋原因
• CI 中的 flaky tests
• 之前修過，但修法沒有真正生效的 bug
• 錯誤訊息出現在很深的 call stack 裡
• 錯誤狀態、檔案殘留、路徑不對、race condition、時序問題

什麼情況下它不太適合

只有在任務本質上不是除錯時，才建議跳過它，例如：

• 很直接的功能開發
• 沒有失敗行為需要解釋的例行 refactor
• 純外觀或文案調整

即使如此，只要你處理的是「非預期行為」，systematic-debugging 通常仍然是更穩妥的起點。

如何使用 systematic-debugging skill

安裝 systematic-debugging 的方式

如果你是沿用這個生態系常見的 Skills CLI 模式，可用以下指令安裝：

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

安裝後，你可以從 agent 環境直接呼叫它；或者進入 skill 資料夾，讀原始檔案並手動照它的流程操作。

先讀這些檔案

如果你想快速掌握高資訊密度的 systematic-debugging guide，建議依序閱讀：

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

這樣排序的原因是：

• SKILL.md 提供必須遵守的四階段流程
• root-cause-tracing.md 適合處理症狀出現在下游很遠處的情況
• condition-based-waiting.md 提供 flaky async tests 的具體修正模式
• defense-in-depth.md 幫你把最終修法做得更穩
• find-polluter.sh 是用來隔離測試污染的實用工具

這個 skill 需要你提供哪些輸入

systematic-debugging usage 的品質，非常依賴你提供的輸入。請盡量給出：

• 精確的錯誤訊息
• stack trace
• 重現步驟
• 預期行為與實際行為
• 環境細節，例如 OS、runtime、test runner、只在 CI 發生或只在本機發生
• 最近的程式碼變更
• 問題是穩定可重現，還是偶發 flaky
• 你已經試過哪些做法

如果缺少這些資訊，模型就更容易開始靠猜。

把粗略的 bug 回報整理成有效 prompt

弱的 prompt：

Test is failing. Help fix it.

更好的 prompt：

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

這類 prompt 之所以更有效，是因為它要求先輸出調查結果，再進入實作。

一個實用的 prompt 模板

你可以用這個結構來做 systematic-debugging usage：

• Issue：哪裡壞了
• Reproduction：精確指令或重現步驟
• Evidence：logs、trace、截圖、失敗 assertion
• Scope：只在 local、只在 CI、某一台機器，還是所有環境
• Recent changes：commits、dependency 升級、config 變更
• Constraints：不能改 API、需要最小 patch、有 deadline 等
• Request：先調查 root cause，再提出一個修法

範例：

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

依序遵守四階段 workflow

這個 repo 的核心是四個階段。實務上可這樣使用：

1. Root cause investigation
   仔細讀錯誤、穩定重現、檢查最近改了什麼，並收集證據。
2. Pattern analysis
   觀察是否有時序、環境、輸入型態、狀態洩漏，或 call-chain 相關模式。
3. Hypothesis testing
   一次只建立一種解釋並驗證，不要同時改很多變數。
4. Implementation
   只有在證據已支持某個原因之後，才實作修正並驗證。

如果第 1 階段做得不扎實，後面每一步都會變差。

如何用 systematic-debugging 處理 flaky tests

這個 repo 在這方面提供的協助比多數同類資源更落地。如果某個測試依賴 sleep、setTimeout 或任意等待時間，請直接看 condition-based-waiting.md 與 condition-based-waiting-example.ts。

關鍵轉換是：

• 壞模式：猜非同步工作大概要多久
• 更好的模式：等待能證明工作已完成的條件成立

這點很重要，因為很多看似「隨機」的失敗，實際上是被時序猜測掩蓋的 race condition。

當症狀出現在下游時，怎麼用 systematic-debugging

如果錯誤出現在很深的 stack 中，或離壞資料真正產生的位置很遠，就該用 root-cause-tracing.md。流程是：

• 找出直接失敗的那一行
• 往上追一層 caller
• 持續往上追，直到找到錯誤狀態第一次出現的位置
• 在來源處修，不要只在 crash 點補洞

這是 systematic-debugging skill 最有價值的部分之一，因為很多 bug 其實都是更早之前無效狀態的後續症狀。

如何使用 polluter finder

如果某些測試會留下檔案、資料夾或狀態，先看 find-polluter.sh，通常比自己臨時亂寫迴圈來得更有效。

使用模式：

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

腳本中的範例：

./find-polluter.sh '.git' 'src/**/*.test.ts'

當失敗真正原因是隱性的測試污染，而不是表面上失敗的那個測試時，這個工具特別有用。

最容易得到好結果的常見 workflow

一個可靠的 systematic-debugging install 與首次使用流程如下：

1. 安裝 skill
2. 讀 SKILL.md
3. 收集精確的失敗證據
4. 先要求 agent 調查，不要修
5. 選出證據最充分的假設
6. 只驗證那一個假設
7. 實作一個聚焦的修正
8. 如果 bug 來自無效資料或多個入口路徑，再補上驗證或 defense-in-depth

這樣做可以避開最常見的失敗模式：還沒理解故障，就先改程式碼。

使用這個 skill 時不要做什麼

不要要求 systematic-debugging：

• 一開始就腦暴很多修法
• 還沒重現 bug 就大幅改寫一大片程式
• 不用解釋、只求「先讓測試過」
• 同時修補多個懷疑原因

這些捷徑都直接違反這個 skill 的設計，也會拉低輸出品質。

systematic-debugging skill 常見問題

systematic-debugging 只適合複雜 bug 嗎？

不是。這個 repo 的立場是：即使是簡單 bug，也一樣有根因。當問題看起來簡單到讓人想立刻打一個 quick patch 時，這個 skill 反而最有價值。

它和一般除錯 prompt 有什麼不同？

一般 prompt 往往鼓勵快速給答案，也比較容易接受推測式修補。systematic-debugging 會強迫模型把調查、假設與實作切開。通常這會帶來更少的錯誤 patch，以及更好的說明品質。

systematic-debugging 對新手友善嗎？

是的，前提是你能提供具體證據。流程雖然嚴格，但步驟其實不難理解：重現、檢查、追溯、一次驗證一個想法，最後才修。對新手來說，這甚至可能更有幫助，因為它能防止隨機試錯。

什麼時候不該用 systematic-debugging？

以下情況不適合把它當成主要模式：

• 功能發想
• 架構腦力激盪
• 和故障無關的程式碼生成
• 沒有壞掉行為需要解釋的純視覺調整

當你需要的是「找出原因」，而不只是「打一個 patch」時，再用它。

systematic-debugging 能幫忙處理只在 CI 發生的失敗嗎？

可以。它很適合處理只在 CI 出現、或對負載敏感的故障，因為它會推著你比較環境差異、重現觸發條件，並檢查時序與狀態假設，而不是直接猜。

它能處理 flaky async tests 嗎？

可以，而且這個 repo 在這點上表現比平均更強。condition-based-waiting.md 和範例 TypeScript 檔案，提供了非常具體的路徑，幫你從任意等待改成基於條件的同步。

這個 skill 有附工具，還是只有方法建議？

主要是流程指引，但也附了一些具體的輔助檔案。最實用的是 find-polluter.sh；另外，condition-based waiting 的範例也能直接套用到某些 TypeScript 測試設定中。

我可以把 systematic-debugging 用在任何技術棧嗎？

大致上可以。核心方法與技術棧無關。雖然範例偏向 TypeScript、shell 與測試工作流，但整套調查流程適用於多數語言與 framework。

如何改善 systematic-debugging skill 的使用效果

在要求修法之前，先提供更好的證據

影響最大的槓桿就是輸入品質。想得到更好的 systematic-debugging 結果，請盡量附上：

• 一個精確的重現指令
• 一段完整而精確的錯誤內容
• 一個最小失敗測試或檔案
• 最近改了什麼
• 這個問題是否每次都能重現

這樣能讓 skill 根據證據運作，而不是靠推論補空白。

先要求輸出調查結果，再進入實作

高品質 prompt 會明確阻止過早修補。例如：

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

這能提升回答品質，因為它在讀症狀與改程式之間，先建立一道檢查點。

強制一次只驗證一個假設

很常見的失敗模式，是把好幾個可能原因一起混進同一個 patch。你可以要求：

• 目前最主要的假設
• 能推翻它的最小測試
• 什麼結果會支持它成立

這樣能讓 workflow 持續符合 skill 的原始意圖。

在 flaky-test 情境下，改善 systematic-debugging prompt

當你用 systematic-debugging for Debugging 處理 flaky tests 時，請提供：

• 測試通過／失敗的頻率
• 失敗是否和 parallelism 或 CI 有關
• 是否有使用 sleeps、waits、retries 或 polling
• 測試實際想觀察的是哪個事件或狀態

這會讓模型更容易辨識 condition-based-waiting.md 是否就是當前最相關的搭配模式。

不要只看 SKILL.md，也要用貼近原始碼的輔助檔案

如果第一次輸出看起來太泛，請明確引導模型去看這些支援文件：

• root-cause-tracing.md：處理下游症狀
• condition-based-waiting.md：處理時序／race 問題
• defense-in-depth.md：處理驗證與防禦策略
• find-polluter.sh：處理測試污染

當 agent 真的使用這些專門的輔助材料，而不只依賴主流程摘要時，這個 skill 的效果會更好。

第一輪之後，收斂範圍

如果第一輪結果太廣，可以再補充：

• 要檢查的精確子系統
• 你懷疑壞資料進入的邊界位置
• 問題第一次出現的 commit
• 最小可重現案例

過於寬泛的除錯 prompt，通常只會得到寬泛的除錯計畫。範圍縮小，根因分析通常會更有效。

不只改善診斷，也要改善最後的修法

找出 root cause 之後，可以再要求：

• 最小修正
• 一個 regression test
• 一層可防止再次發生的 validation layer

這時候 defense-in-depth.md 就派得上用場。如果 bug 來自無效輸入，或某些假設其實很容易被繞過，單一 patch 往往不夠。

注意這些常見失敗模式

不理想的 systematic-debugging usage 常見原因包括：

• 錯誤內容不完整
• 沒有可靠的重現方式
• 太早要求修法
• 每次測試之間同時改了很多東西
• 把第一個看起來合理的解釋當成已被證明

只要避開這些問題，這個 skill 通常會比泛泛的「幫我 debug」prompt 更有價值。