Debug Mode
基於 Cursor 官方 Debug Mode 文件解釋假設、插樁、復現、日誌分析、精準修復和清理流程。
Debug Mode 是 Cursor Agent 的排障模式。官方文件強調：它不會一開始就寫程式碼，而是先生成假設、新增日誌、利用執行時資訊定位 root cause，再做 targeted fix。
閱讀目標：讀完本章，你應該能判斷什麼時候切 Debug Mode，並能按“復現、插樁、日誌、根因、修復、清理”的順序驗收一次 bugfix。
1. 和 Agent Mode 的差別
官方 Help Center 的區分很清楚：知道要構建什麼，用 Agent Mode；不知道為什麼壞了，用 Debug Mode。
| 模式 | 適合什麼 | 主要風險 |
|---|---|---|
| Agent Mode | 你知道要實現什麼功能或修改什麼行為 | 過早寫程式碼，可能按錯誤假設擴散修改 |
| Debug Mode | 某個現象壞了，需要找 root cause | 需要使用者配合復現，否則缺少執行時證據 |
Debug Mode 的價值在於讓 Agent 先調查。它會看 error messages、stack traces、runtime context，先識別根因，再應用針對性修復。
2. 什麼時候用 Debug Mode
官方文件列出的適合場景包括：
| 場景 | 為什麼適合 Debug Mode |
|---|---|
| 能復現但讀程式碼看不出原因 | 需要執行時日誌證明真實路徑 |
| Race conditions（競態條件）和 timing issues（時序問題） | 問題依賴執行順序或 async behavior |
| Performance problems 和 memory leaks（記憶體洩漏） | 需要 runtime profiling（執行時效能取樣）或執行時證據 |
| Regression（迴歸 bug，過去能工作、新版壞了） | 需要追蹤過去能工作、現在不工作的變化 |
| 普通 Agent 多次修不好 | 需要換成基於證據的排障流程 |
暫時不適合：
- 你根本無法復現問題，也沒有日誌、截圖、stack trace。
- 需求其實是新功能開發，而不是 bug investigation。
- 你只需要解釋程式碼，不需要執行或插樁。
3. 官方流程
官方 Debug Mode 流程可以拆成六步。
flowchart TD
Bug["描述 bug / 貼上錯誤"] --> Explore["Explore and hypothesize"]
Explore --> Instrument["Add instrumentation"]
Instrument --> Reproduce["使用者按步驟復現"]
Reproduce --> Logs["Analyze collected logs"]
Logs --> Fix["Make targeted fix"]
Fix --> Verify["Verify and clean up"]| 步驟 | 官方行為 | 你要看什麼 |
|---|---|---|
| Explore and hypothesize | Agent 探索相關檔案並生成多個 root cause 假設 | 有沒有遺漏明顯路徑 |
| Add instrumentation（插樁，臨時插入日誌 / 斷點觀察執行時） | Agent 新增 log statements，資料會傳送到 Cursor extension 中的 local debug server | 插樁是否只覆蓋必要路徑 |
| Reproduce the bug | Debug Mode 要求你按具體步驟復現 | 步驟是否能穩定觸發現象 |
| Analyze logs | Agent 讀取收集到的 logs | 結論是否來自執行時證據 |
| Make targeted fix | Agent 做集中修復，通常只是幾行程式碼 | diff 是否直接對應根因 |
| Verify and clean up | 重新復現驗證，確認後移除所有 instrumentation | 是否清理日誌和臨時程式碼 |
Debug Mode 的商業級價值不在“改得快”，而在“少猜”。如果 Agent 沒有日誌、呼叫堆疊、復現步驟或 runtime context，就不能把結論當成根因。
4. 怎麼進入 Debug Mode
官方 Help Center 給出這個入口：
- 開啟 Agent panel：Mac 用
Cmd + I，Windows / Linux 用Ctrl + I。 - 按
Shift + Tab迴圈模式，或使用 mode picker dropdown 切到 Debug Mode。 - 描述 bug，或貼上 error message。
- 按 Return，讓 Agent 開始調查並提出修復。
官方 docs 頁也說明，可以在 Agent 的 mode picker dropdown 切換，或用 Shift+Tab 快速切換。
5. 給 Debug Mode 的輸入
Prompt 要儘量提供可復現證據。
| 資訊 | 為什麼重要 |
|---|---|
| Expected behavior | Agent 需要知道正確結果是什麼 |
| Actual behavior | Agent 需要知道現在怎麼壞 |
| Reproduction steps | 沒有復現，日誌通常沒有價值 |
| Error message / stack trace | 幫助定位呼叫鏈 |
| 發生環境 | 本地、瀏覽器、CLI、CI、特定賬號或資料狀態 |
| 最近變化 | regression 場景下幫助縮小 diff |
深讀：為什麼 Debug Mode 會要求你親自復現
很多 bug 不是“讀程式碼”能確認的，尤其是 timing、async、狀態競爭、效能和記憶體問題。Debug Mode 新增 instrumentation 後，需要你按步驟復現，讓日誌捕獲真實執行路徑。
這一步把使用者留在迴圈裡：Agent 負責假設和插樁，使用者負責觸發現象。最後的修復應該能被同一套復現步驟再次驗證。
6. 驗收清單
Debug Mode 結束前，至少檢查：
- 是否列出過多個假設，而不是直接改程式碼。
- 是否新增過必要 instrumentation。
- 是否由你按步驟復現過問題。
- 是否基於 logs、stack traces 或 runtime context 定位根因。
- 最終 diff 是否集中，避免擴散重構。
- 所有 instrumentation 是否已清理。
- 是否用同一套復現步驟驗證修復。
- 是否補了測試或留下手工驗證證據。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Debug Mode 和 Agent Mode 的本質差別是什麼？
- 為什麼 Debug Mode 需要復現步驟和執行時證據？
- 修復完成後，為什麼必須清理 instrumentation？
透過標準：你能給一個疑難 bug 寫出 Debug Mode prompt，並能判斷最終修復是否真的來自 root cause，而不是猜測。
官方來源
- Cursor Debug Mode —— 官方說明適用場景、六步工作流、插樁、復現、日誌分析、修復和清理。
- Cursor Help: Debug Mode —— Help Center 說明入口、模式差異和使用步驟。