前言¶
調試是開發者繞不開的日常。Bug 出現時，人類工程師往往有一套習慣：先復現、再縮小範圍、提出假設、用證據驗證，最後做最小修復。可當你把問題交給 AI 編程助手時，常見畫風卻是——Agent 連續改好幾處代碼、加一堆防禦性判斷，問題有時碰巧好了，有時卻引入新迴歸，你甚至說不清它到底查到了什麼。
systematic-debugging 正是針對這一痛點：它來自社區精選倉庫 awesome-cursor-skills，把「復現 → 隔離 → 假設 → 驗證 → 修復」這套結構化調試流程寫進 SKILL.md，教 Agent 按步驟排錯，而不是隨機改代碼碰運氣。對經常讓 Cursor、Claude Code 等工具幫忙查 Bug 的開發者來說，值得一裝。
這是什麼¶
systematic-debugging 是一個 Agent Skill，維護者爲 Spencer Pauly 的 awesome-cursor-skills 項目，歸類在 Workflow（工作流）技能中。
它的 frontmatter 定義如下：
---
name: systematic-debugging
description: Structured debugging methodology — reproduce, isolate, hypothesize, verify. Covers git bisect, binary search, logging, and minimal reproduction.
user-invocable: true
---
一句話定位：用可復現的步驟約束 AI 的調試行爲——先拿到穩定復現路徑，再縮小故障範圍，形成可檢驗的假設，用最小實驗驗證，最後做最小修復並回歸測試。Skill 正文明確寫了 「Debug methodically instead of randomly changing code」（有條理地調試，而不是隨機改代碼），這正是它與普通「幫我修 Bug」提示詞的核心區別。
該 Skill 遵循通用的 SKILL.md 開放格式，可在 Cursor、Codex CLI、Claude Code 等支持 Agent Skills 的工具中使用；各工具的安裝目錄略有差異，下文會分別說明。
核心功能與亮點¶
五步調試流程¶
Skill 把調試拆成五個階段，Agent 應按順序推進，而不是跳步亂改：
1. Reproduce（復現）
在動手改代碼之前，必須先穩定復現 Bug：
- 記錄觸發問題的精確步驟
- 明確「期望行爲」與「實際行爲」的差異
- 確認問題是否可穩定復現（而非偶發）
- 記錄運行環境：操作系統、Node 版本、瀏覽器等
Skill 寫得很直白：「If you can’t reproduce it, you can’t fix it.」——復現不了，就繼續向用戶追問細節，不要憑空猜測。
2. Isolate（隔離）
把故障範圍一點點縮小，Skill 提供了三種常用手段：
二分搜索代碼庫：註釋掉一半邏輯，看 Bug 是否仍在；根據結果繼續在另一半里二分，直到定位到具體模塊。
Git bisect：適合「以前能用、某次提交後壞了」的場景，官方給出了完整命令流程：
git bisect start
git bisect bad # 當前提交是壞的
git bisect good <sha> # 這個提交還是好的
# Git 檢出中間版本 —— 測試它
git bisect good # 或 git bisect bad
# 重複直到找到第一個壞提交
git bisect reset # 完成後重置
按層隔離：從前端/後端、數據庫、API、單個組件等維度逐層剝離——查 Network 面板、直接 curl 接口、單獨渲染組件，判斷問題落在哪一層。
3. Hypothesize（假設）
要求 Agent 形成具體、可檢驗的假設，而不是模糊結論。Skill 給了正反例：
- 差：「數據好像有問題」
- 好：「
userId爲 null，因爲 auth 中間件沒有在這條路由上執行」
4. Test the Hypothesis（驗證假設）
用最小實驗證明或推翻假設：
- 在可疑位置加
console.log或斷點 - 檢查懷疑變量的實際值
- 假設錯誤則回到第 3 步；假設成立則找到根因
5. Fix and Verify（修復與驗證）
- 做最小改動修復根因，而非掩蓋症狀
- 用原始復現步驟確認 Bug 已消失
- 檢查是否引入迴歸
- 補寫一條能捕獲此類 Bug 的測試
場景化調試工具表¶
Skill 還整理了一張「場景 → 工具」對照表，幫助 Agent 快速選對手段：
| 場景 | 建議工具 |
|---|---|
| 「以前能用」 | git bisect |
| 「不知道這段代碼在哪跑」 | 在可疑函數入口/出口加日誌 |
| 「數據看起來不對」 | 逐步檢查每個變換環節 |
| 「只在生產環境失敗」 | 對比環境變量、查日誌、用生產數據本地復現 |
| 「偶發失敗」 | 排查競態、時序、未初始化狀態 |
| 「錯誤信息沒用」 | 在代碼庫中搜索該錯誤的拋出位置 |
常見 Bug 模式清單¶
Skill 列舉了 Agent 應優先留意的典型模式，包括：Off-by-one、Null/undefined、競態條件、React stale closure、類型強制轉換（== vs ===）、漏寫 await、本地與 CI/生產環境不一致等。這不是玄學清單，而是把人類調試經驗編碼成檢查項，減少 Agent 在常見坑上反覆繞圈。
四條鐵律¶
- Never guess — always verify with evidence（不猜測，用證據驗證）
- Fix the root cause, not the symptom（修根因，不修表象）
- 15 分鐘無進展就退一步重新隔離
- 記錄已嘗試的方案，避免重複失敗路徑
user-invocable: true 表示用戶也可以在 Agent 對話裏通過 /systematic-debugging 顯式調用，強制 Agent 走這套流程。
安裝與啓用¶
awesome-cursor-skills 的 Skills 均爲「複製即用」：SKILL.md 放進對應工具的 skills 目錄即可，無需額外依賴或編譯。
在 Cursor 中安裝¶
方式一：手動複製（推薦，便於團隊共享）
-
從官方倉庫獲取文件：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging -
在項目根目錄創建目錄並放入
SKILL.md：
mkdir -p .cursor/skills/systematic-debugging
# 將 SKILL.md 複製到 .cursor/skills/systematic-debugging/SKILL.md
- 重啓 Cursor 或重新打開項目，Agent 會自動發現該 Skill。
根據 Cursor 官方 Skills 文檔，Cursor 會從以下位置掃描 Skill：
| 位置 | 作用域 |
|---|---|
.cursor/skills/ |
項目級，可提交 Git 與團隊共享 |
.agents/skills/ |
項目級，跨工具兼容 |
~/.cursor/skills/ |
用戶級，所有項目可用 |
~/.agents/skills/ |
用戶級，跨工具兼容 |
文件夾名建議與 frontmatter 中的 name 一致（小寫、連字符），即 systematic-debugging。
方式二：從 GitHub 導入
Cursor 支持通過 Customize → Rules → Add Rule → Remote Rule (Github) 填寫倉庫地址導入；也可用內置 /migrate-to-skills 將舊規則遷移爲 Skill 格式。
在 Claude Code / Codex CLI 中使用¶
這類工具同樣識別 SKILL.md 通用格式。Claude Code 通常讀取項目下的 .claude/skills/ 或 .agents/skills/；Codex CLI 讀取 .codex/skills/ 等目錄（Cursor 文檔亦提到爲兼容會掃描這些路徑）。將 systematic-debugging 目錄複製到對應工具的 skills 根目錄即可，具體以各工具當前文檔爲準。
安裝完成後，可在 Cursor Settings → Rules → Agent Decides 區域看到已加載的 Skill；描述字段會幫助 Agent 判斷何時自動啓用。
典型用法示例¶
自動觸發¶
當你在 Agent 對話中描述 Bug，例如：
登錄後跳轉到個人頁，用戶名顯示爲空，但 Network 裏接口返回的數據是對的。
Agent 會根據 description 中的 reproduce, isolate, hypothesize, verify 等關鍵詞，自動匹配並加載 systematic-debugging，按五步流程推進：先讓你確認復現步驟與環境，再建議查 Network、隔離前端渲染層、提出「props 未傳遞」類假設，並用最小 log 驗證。
顯式調用¶
若你希望強制走結構化流程，在 Agent 輸入框輸入：
/systematic-debugging
然後描述問題。user-invocable: true 保證該 Skill 可作爲斜槓命令直接喚起，適合 Agent 此前「亂改一氣」、你需要它重新按方法論來一遍的場景。
Git bisect 協作示例¶
假設你知道 v1.2.0 正常、當前 main 分支異常，可以讓 Agent 在 systematic-debugging 指導下執行：
git bisect start
git bisect bad HEAD
git bisect good v1.2.0-tag
# 每一輪：運行測試或手動驗證 → git bisect good/bad
git bisect reset
Skill 要求 Agent 在 bisect 過程中記錄每次測試結果，最終 pinpoint 引入迴歸的提交，而不是直接在大範圍 diff 裏盲改。
與「最小復現」配合¶
隔離階段，Skill 強調構造最小可復現用例——去掉無關依賴和分支，只保留觸發 Bug 的必要代碼。這對 AI 尤其重要：上下文越小，Agent 越不容易被無關文件干擾，假設也更容易驗證。
適用場景與注意事項¶
適合誰、什麼場景：
- 日常讓 AI 幫忙查 Bug，但受夠了「改十處碰運氣」
- 迴歸問題、偶發問題、環境差異問題，需要 Agent 先復現再動手
- 團隊希望把調試 SOP 寫進倉庫，新成員和 Agent 共用同一套流程
- 技術負責人想降低 AI 引入靜默迴歸的風險
注意事項：
- Skill 是方法論，不是萬能補丁。它教 Agent 怎麼查，不替代你對業務邏輯的判斷；複雜分佈式系統可能還需結合鏈路追蹤、APM 等工具。
- 復現成本高的 Bug（僅生產、極低概率）Skill 也會建議追問細節和環境對比，Agent 仍可能無法一次定位，需要人工配合提供日誌與數據。
- 不要與「快速瞎改」混用。若同一會話裏你又提示「別管了直接全改一遍」，可能沖淡 Skill 約束；顯式
/systematic-debugging效果更好。 - 版本隨倉庫更新。awesome-cursor-skills 持續維護，建議定期
git pull或重新複製，以獲取新增的 Bug 模式或工具建議。 - 團隊規範可二次擴展。你可以在項目內 fork 該 Skill，加入團隊特有的日誌規範、測試命令或禁止操作（例如「未復現前禁止改生產配置」）。
小結¶
調試能力不會因爲是 AI 在執行就可以省略方法論。systematic-debugging 把復現、隔離、假設、驗證、最小修復這套工程師常識寫進 SKILL.md，讓 Agent 排錯時有章可循，少做無效修改，多留可追溯證據。對於 AI 編程工具用戶，這是一個輕量、零依賴、複製即用的 Workflow Skill，值得放進 .cursor/skills/ 試一輪。
官方 Skill 地址：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging
awesome-cursor-skills 項目主頁：
https://github.com/spencerpauly/awesome-cursor-skills
