debugging-and-error-recovery

debugging-and-error-recovery 技能概覽

debugging-and-error-recovery 技能是一套結構化的除錯方法，讓你在沒有猜測的情況下診斷失敗原因。它特別適合面對測試失敗、建置破損、執行期行為異常、雜訊很多的 log，或是只有在變更之後才冒出的 regression 的開發者與 agent。如果你需要用 debugging-and-error-recovery 技能來做 Debugging，目標不只是「把錯誤修掉」，而是要先保全證據、重現問題、找出根因，再繼續動手改更多東西。

這個技能適合用在什麼情境

這個技能最適合「問題是真的存在，但原因還不清楚」的時候。它強調先停止線上的思維：不要在已知問題還沒解掉之前，還一直往前交付功能。這讓它很適合測試驅動流程、事故分流，以及任何一個小失誤都可能連鎖引發誤導性後續失敗的 repo。

誰應該安裝它

如果你經常搭配 agent 除錯程式碼，而且想要一套可重複的流程，而不是臨時想提示詞，那就值得安裝 debugging-and-error-recovery。它也特別適合想把 logs、失敗的 CI、bug 報告，更穩定地交接成修正計畫的團隊。

這個技能的差異在哪裡

它的核心價值是紀律：先重現、再保留證據、依序診斷，最後驗證修補並防止再發。這比一般「幫我除錯」的 prompt 更能直接做決策，因為它明確告訴 agent 當第一次嘗試失敗時應該怎麼行動。

如何使用 debugging-and-error-recovery 技能

安裝並載入這個技能

先透過 repo manager 執行 debugging-and-error-recovery 的安裝流程，接著先閱讀 SKILL.md。在這個 repository 裡，沒有額外的 helper scripts 或支援資料夾，因此這個技能刻意保持輕量，把重心放在單一、清楚的流程，而不是一整套龐大的 toolchain。

把含糊的 bug 變成可用的 prompt

debugging-and-error-recovery 的使用效果最好，前提是你一開始就提供三樣東西：症狀、證據、邊界條件。比如不要只說「幫我修 app」，而是說：「npm test 在 abc123 這個 commit 之後，user-auth.spec.ts 失敗了；這裡是 stack trace、預期行為，以及最後一次正常執行的結果。」這樣就能給這個技能足夠的上下文去重現並分流問題，而不是憑空編造理論。

建議的最佳操作流程

先要求 agent 在修改程式碼之前保留證據並重現問題。接著，讓它依序走完分流步驟：重現、隔離、檢查最近變更、找出根因、以最小幅度修正、再驗證。這個流程很重要，因為這個技能是為 debugging-and-error-recovery 最佳化，不是用來擴充功能或做大範圍重構的。

先閱讀這些 repository 檔案

在這個 repo 裡，第一個要讀的檔案是 SKILL.md。沒有其他參考資料、規則或 scripts 可供查閱，所以導入上更簡單，但也代表你要在 prompt 裡自己補上專案專屬的限制、commands 和環境資訊。

debugging-and-error-recovery 技能 FAQ

它比一般的除錯 prompt 更好嗎？

通常是的，前提是你要的是一致性。一般 prompt 可以要求修正，但 debugging-and-error-recovery 會多一套流程：先停下來、保留證據、重現、依序診斷、再驗證。這能減少那種「先快速修一下」卻常常把真正問題遮住的行為。

什麼情況下不該使用它？

不要把它用在推測性的架構工作、功能規劃，或是根本沒有可觀察失敗的任務。如果你是在探索設計方案，而不是從錯誤中復原，那麼 debugging-and-error-recovery 這份 guide 可能會太受限，不太適合。

這個技能適合初學者嗎？

適合，因為流程非常明確。初學者會受益於它直接告訴你該收集什麼、以及該按什麼順序調查。主要限制是：初學者仍然需要提供真實症狀，而不是只丟一個泛泛的求助請求。

它適合一般的 agent 工作流程嗎？

適合。當 agent 能存取 logs、tests、diffs，以及可執行的環境時，它就很合拍。如果 agent 無法檢視證據或驗證變更，它的效果就會下降，因為 recovery loop 需要回饋訊號才能運作。

如何改進 debugging-and-error-recovery 技能

提供更強的失敗輸入

要讓 debugging-and-error-recovery 的輸出更好，最有效的方法就是提供精確的失敗模式、觸發它的 command、預期結果、實際結果，以及最近的變更。比如：「pnpm test 只有在 Linux 上升級 zod 後才失敗；這是 diff 和 stack trace。」這樣可以立刻縮小搜尋範圍。

保留技能可以直接使用的上下文

把 logs、screenshots、重現步驟、環境資訊，以及任何已知正常的基準都一起提供。當這個技能能夠比較「前後差異」而不是從空白描述開始時，效果會更好。如果 bug 是偶發性的，也要明講，並說明哪些因素會讓它更容易出現。

要求最小修正與驗證

一個好的 debugging-and-error-recovery 使用 prompt，應該要求最小且安全的修正，再加上驗證計畫或測試更新。這樣可以避免修正過頭，也讓輸出更適合重視穩定性的團隊採用。

第一次嘗試後持續迭代

如果第一輪結果還不明確，就用下一個最有價值的證據來修正 prompt：更精準的重現步驟、更具體的 stack trace，或是懷疑的精確 file path。debugging-and-error-recovery 技能最有效的時候，是每一次迭代都在消除不確定性，而不是把同一個症狀再說一遍。