debugger

debugger skill 概覽

debugger skill 是做什麼用的

debugger skill 是一套結構化的除錯流程，目的是比單純丟一句「哪裡有問題？」更快找出真正的根因。它特別適合用在程式碼拋錯、行為異常、改版後回歸，或只在特定環境才會失敗的情況。它不會一開始就直接跳到修復，而是強調真實除錯工作裡最重要的順序：重現、隔離、分析、修復、驗證。

哪些人適合安裝這個 debugger skill

這個 debugger skill 很適合想把 Debugging 做成可重複流程的開發者、AI coding agents 與技術團隊，而不是每次都靠臨場猜測排查。特別是如果你經常從 stack trace、logs、片段化的 bug 回報，或不完整的重現步驟開始調查，它會很有幫助。它的重點不是提供深度框架專精，而是幫你在不同專案裡建立更穩定的除錯紀律。

它幫你完成的核心工作是什麼

真正要解決的，不只是「解釋這個錯誤訊息」。而是把一個模糊的故障，整理成清楚的調查路徑：最近改了什麼、怎麼重現、該從哪裡縮小範圍、要收集哪些證據、最後又該怎麼驗證修復是否真的成立。當團隊一直浪費時間在猜原因，或反覆只修到表面症狀時，安裝這個 debugger skill 的價值就會特別明顯。

為什麼這個 debugger skill 特別值得裝

這個 debugger skill 真正有區隔性的地方，在於它是可執行的工作流，而不只是提示詞。repo 內包含：

• SKILL.md 裡的分階段除錯流程
• references/checklist.md、references/errors.md、references/patterns.md 裡的快速參考除錯輔助資料
• scripts/debug_report.py 這個實用的報告產生器

這種組合讓 debugger skill 在即時事件處理、故障調查這類場景裡，比單純 prompt template 更實用。你拿到的不只是流程，還有 checklist、常見失敗類型，以及可交接的調查產物。

它不打算取代什麼

這不是某種語言專用 debugger、IDE extension，也不是 tracing platform。它不會取代 runtime tools、profilers 或 framework docs。如果你的主要需求是互動式單步執行、記憶體檢查，或協定層級 tracing，還是應該直接使用那些工具，把這份 debugger guide 當成它們外圍的推理層即可。

如何使用 debugger skill

安裝位置與 repo 路徑

這個 skill 位於 zhaono1/agent-playbook repo 內的 skills/debugger。如果你使用的 skill loader 支援 GitHub 來源，直接從該 repository 安裝並指定 debugger skill 即可。常見做法如下：

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

如果你的安裝方式不同，重點是要讓系統載入 skills/debugger 這個目錄，這樣 agent 才能讀到 SKILL.md 與支援用的 references/、scripts/ 檔案。

建議先讀這些檔案

想快速上手，建議依照以下順序閱讀：

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

這個順序其實對應了真實的 debugger 使用流程：先看工作流，再看調查 heuristics，接著看錯誤分類，最後補上文件化支援。

debugger skill 在實務上通常怎麼被觸發

這個 repository 的設計，是在使用者回報以下情況時啟動：

• 發生 error 或 exception
• 行為不符合預期
• 「debug this」
• 「why isn’t this working?」

實際上，debugger skill 最好用的方式，是你明確把需求描述成除錯任務，並附上證據。例如：

「Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.」

這種 prompt 的品質，會比單純說「fix this bug」高很多。

debugger skill 需要哪些輸入

要把 debugger skill 用好，關鍵在於提供具體輸入。能給多少就給多少：

• 精確的錯誤文字
• stack trace
• 預期行為 vs 實際行為
• 可重現步驟
• 最近的程式碼或設定變更
• 環境資訊
• 相關 logs
• 已縮小過的檔案或元件範圍

這個 skill 的流程預設你會先收集證據，所以比起少了實作細節，缺少重現步驟或實際輸出，對結果品質的影響通常更大。

把模糊需求改寫成更強的 debugger prompt

弱的 prompt：
「Why does this fail?」

更強的 prompt：
「Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.」

這樣寫之所以有效，是因為它：

• 明確指出除錯目標
• 交代預期行為與實際行為
• 包含環境不一致的資訊
• 說明近期變更
• 要求先調查再修補

建議的 debugger workflow

以下是一套適合實務使用的 debugger guide：

1. 精準重現問題。
2. 記錄預期行為與實際行為。
3. 用 git log --oneline -10 檢查近期變更。
4. 蒐集 logs 或 traces。
5. 用最小重現案例或 binary search 進行隔離。
6. 把故障對應到某個錯誤類型。
7. 建立根因假設。
8. 測試最小且最可能有效的修復。
9. 以回歸測試驗證結果。

這基本上就是 skill 內編碼的流程；但如果你在使用時也明確照這個順序走，當 agent 太早開始提修法時，會特別有幫助。

把 reference 檔案當成決策輔助

這些支援檔案雖然不長，但會明顯影響輸出品質：

• references/checklist.md 用來確保整個 session 不偏掉：重現、隔離、根因、修復、回歸驗證都不能漏。
• references/patterns.md 在問題範圍太廣或雜訊太多時特別有用；裡面會引導你使用 binary search、針對性 logging、最小重現縮減。
• references/errors.md 幫助你把常見故障分類，像是 null access、race conditions、config mismatch、data shape drift。

如果第一次跑出來的 debugger 結果太空泛，就很適合回頭用這些檔案。它們比起教語法，更適合拿來把調查路徑磨得更精準。

產生可重用的 debug report

如果你想留下可文件化的調查產物，可以使用：

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

這會建立一份 markdown 報告模板，裡面包含 summary、environment、repro steps、logs、root cause、fix、regression tests 與 follow-ups 等區段。對團隊除錯來說，這是整個 repository 最實用的部分之一，因為它能把原本很容易散失的調查過程，轉成可以 review、可以交接的文件。

debugger skill 最適合哪些 Debugging 場景

這個 debugger skill 在以下情況特別有價值：

• bug 可以重現，但原因不明顯
• 有 logs，但雜訊很多
• 故障是在某次變更之後才開始出現
• 問題同時跨越 code、config 與 environment
• 你需要先有一套紀律化的 triage 流程，再動手改程式

相對地，如果只是肉眼一看就能發現的小型語法錯誤，或者是需要 agent 無法取得的專有營運背景知識的領域事件，它的優勢就沒那麼明顯。

能提升 debugger skill 使用效果的實務技巧

你可以要求這個 skill 把輸出明確拆成：

• facts
• hypotheses
• next checks
• proposed fix
• verification steps

這種結構能避免過早下定論。另外，也可以要求它替可能原因排序，並說明哪些證據可以推翻各自的假設。這樣一來，debugger skill 就不只是「比較聰明的猜測器」，而是更像真正的調查夥伴。

debugger skill 常見問題

這個 debugger skill 真的比一般 prompt 更好嗎

通常是，尤其在問題需要多步驟調查時更明顯。一般 prompt 很容易從症狀直接跳到猜測式修復；而 debugger skill 的優勢在於系統化縮小範圍、蒐集證據、再做驗證。如果 bug 很簡單，而且從單一程式片段就能完全看出問題，那一般 prompt 也可能已經夠用。

debugger 安裝後對新手友善嗎

是的，因為它的核心流程簡單而具體。新手通常能從分階段流程與 checklist 受益最多。需要注意的是，這個 skill 預設你至少能提供一些證據，例如 logs、stack traces 或重現步驟。缺少這些資訊時，任何 debugger guide 都很容易退化成高猜測比例的回答。

這個 debugger skill 可以搭配任何語言或技術棧使用嗎

大致上可以。這個 debugger skill 是以流程為中心，而不是綁定單一語言。它提供的錯誤範例偏向通用，而非框架專屬。這讓它具備不錯的可攜性，但也代表如果你想拿到最佳結果，仍然需要自行補上 stack-specific 的背景細節。

什麼情況不建議使用這個 debugger skill

以下情況可以先跳過：

• 你需要的是互動式 runtime debugging，而不是推理協助
• 問題純粹屬於營運層，且 agent 無法存取系統
• bug 已經確定只是單行 typo
• 你需要的是 repository 裡沒有提供的 vendor-specific 專業知識

遇到這些情況時，應該先用直接工具或領域文件處理。

它對團隊交接與事件追蹤有幫助嗎

有。debug_report.py 這支 script 是最能看出這個 debugger skill 不只是為了一次性對話而設計的地方。它能把一次除錯 session 整理成可重用報告，包含 owner、repro steps、root cause、fix 與 follow-ups。

如何把 debugger skill 用得更好

給 debugger skill 的是證據，不只是症狀

想提升 debugger 輸出品質，最快的方法就是提供原始證據：

• 實際執行的 command
• 完整錯誤文字
• 觸發失敗的輸入
• 發生問題的 environment
• 最近的 commit 範圍
• 你已經試過哪些做法

「Here is the stack trace and the last good commit」會比「it’s broken after my changes」有用得多。

一開始就逼近最小重現案例

debugger 使用上常見的失敗模式之一，就是一開始調查的表面範圍太大。你可以直接要求 skill 幫你找出最小可重現案例。這通常能把 framework setup、無關服務或殘留狀態帶來的雜訊先排除，讓根因更快浮現。

要求它幫你排序假設

當可能原因不只一個時，請明確要求 debugger skill 依「發生機率」與「驗證成本」排序。這樣會得到更合理的調查順序。例如：

「List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.」

這對 flaky tests、integration failures，以及 config drift 特別有用。

把根因與修復品質分開看

另一個很常見的問題，是只要第一個修法讓症狀消失，就直接接受。這時可以用 debugger guide 追問：

• 為什麼會發生這件事
• 是什麼條件讓它得以出現
• 應該用什麼 regression test 來證明它之後不會再發生

這對 null handling、race conditions、mismatched config 這類反覆出現的問題尤其重要。

用 repository 脈絡提升第一次輸出品質

如果 bug 發生在你自己的 codebase，建議提供：

• 可疑檔案
• package 或 service 邊界
• deploy 時間點
• 涉及的 config files
• 問題是否只出現在 local、CI、staging 或 production

當 debugger skill 能把證據和系統邊界連起來思考時，效果會遠比只看一段貼上的 stack trace 更好。

用 references 補強過於空泛的回答

如果第一輪回答太 generic，可以明確要求 agent 使用：

• references/checklist.md 補齊流程完整性
• references/patterns.md 提供隔離方法
• references/errors.md 對照錯誤家族

這是在不重寫整個 prompt 的前提下，實際提升 debugger 結果品質的好方法。

debugger skill 的第一次除錯後，要繼續迭代

好的 debugger 使用方式本來就是迭代式的。第一次輸出後：

1. 先執行一個建議的檢查
2. 把結果帶回來
3. 要求 skill 更新假設
4. 然後再動手改程式

這個循環正是 debugger skill 比靜態 debugger guide 更有價值的地方：它能協助你逐步收斂，而不是一次吐出一大段高猜測性的答案。

結束前補上回歸驗證證據

repository 的 checklist 已經明確把 regression coverage 列進去，而這也確實是最合理的收尾位置。你可以要求 debugger skill 提出最小可行的 test、assertion 或 monitoring check，確保下次同類問題會被抓到。沒有驗證的修復，通常都不能算完整的 Debugging，尤其是在間歇性故障或受環境影響的問題上更是如此。