systematic-debugging 是什麼、怎麼用：Superpowers 的四階段調試 Skill，先找根因再動手修

本文根據 obra/superpowers 倉庫裏該技能的 SKILL.md 與倉庫 README 整理，資料核對於 2026-10-11。skills.sh 榜單當日顯示該技能累計安裝約 28.5 萬次；所在倉庫 obra/superpowers 在 GitHub 約 29.7 萬 Star（同日數據）。技能內容會隨倉庫更新，以倉庫為準。

這個 Skill 做什麼

讓智能體修 bug，它往往看一眼報錯就改，改不好再換個地方改，幾輪下來代碼越修越亂。systematic-debugging 用一條「鐵律」堵住這條路：沒有完成第一階段的根因調查，就不允許提出修復方案。按 description，遇到任何 bug、測試失敗或意料之外的行為，在提出修復之前使用；說明裏列的適用範圍還包括線上故障、性能問題、構建失敗和集成問題，並特別強調越是時間緊、越覺得「就改一行」的時候越不能跳過。

四個階段是：

1. 根因調查：讀完整的報錯、穩定復現、查最近的改動，在多組件系統裏逐層加日誌定位到底是哪一環出錯；
2. 模式分析：找到代碼庫裏能正常工作的類似實現，逐項對比差異；
3. 假設與驗證：一次只提一個假設，做最小的改動去驗證；
4. 實施：先寫一個能復現問題的失敗測試，再修根因，然後確認。

還有一道保險：同一個問題修了三次以上仍不行，就要停下來質疑架構本身，而不是繼續試第四種補丁。

怎麼安裝

systematic-debugging 是 Superpowers 插件裏的一個技能，不單獨發佈：作者的設計是整套一起安裝，由會話開始時注入的引導指令決定各技能何時觸發。Claude Code 裏輸入（命令來自倉庫 README）：

text
/plugin install superpowers@claude-plugins-official

Codex 在 /plugins 裏搜尋 superpowers 安裝；Gemini CLI 用 gemini extensions install https://github.com/obra/superpowers。裝好後在命令選單裏以 /superpowers:systematic-debugging 的形式出現，也會按場景自動觸發。

倉庫整體介紹和其他安裝方式，詳見本站《Superpowers 是什麼、怎麼安裝和使用：Claude Code / Codex 最熱門的 Skills 開發流程框架》。

怎麼用

• 「這個接口偶發 500，幫我查」——它會先收集證據、追數據流，而不是直接改代碼。
• 「CI 上這三個測試掛了」——先復現和定位，再談修復。
• 當你發現它開始亂猜時，說一句「按 systematic-debugging 來」。

目錄裏有幾份配套技術說明：根因回溯、縱深防禦、用「條件等待」替代固定延時（附 TypeScript 示例），以及一個找出「哪條測試污染了環境」的腳本。

適合誰 / 侷限

適合排查不直觀的缺陷、偶發問題和「改了又壞」的情況。對一眼能看出原因的拼寫錯誤，完整四階段顯得繁瑣；它也不能替代可觀測性——沒有日誌和復現手段時，調查階段會卡住，需要你提供環境或數據。

注意事項

• 許可：MIT。
• 會執行命令：調查過程要跑測試、加臨時日誌、查 git 歷史，結束後留意臨時改動是否清理乾淨。
• 與 TDD 技能聯動：修復階段要求先寫失敗測試，項目沒有測試框架時需要先說明怎麼驗證。