---
title: "Debug Mode"
description: "基於 Cursor 官方 Debug Mode 文件解釋假設、插樁、復現、日誌分析、精準修復和清理流程。"
verifiedAt: "2026-05-09"
---

Debug Mode 是 Cursor Agent 的排障模式。官方文件強調：它不會一開始就寫程式碼，而是先生成假設、新增日誌、利用執行時資訊定位 root cause，再做 targeted fix。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼時候切 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 流程可以拆成六步。

```mermaid
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 | 是否清理日誌和臨時程式碼 |

> [!IMPORTANT]
> Debug Mode 的商業級價值不在“改得快”，而在“少猜”。如果 Agent 沒有日誌、呼叫堆疊、復現步驟或 runtime context，就不能把結論當成根因。

## 4. 怎麼進入 Debug Mode

官方 Help Center 給出這個入口：

1. 開啟 Agent panel：Mac 用 `Cmd + I`，Windows / Linux 用 `Ctrl + I`。
2. 按 `Shift + Tab` 迴圈模式，或使用 mode picker dropdown 切到 Debug Mode。
3. 描述 bug，或貼上 error message。
4. 按 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 |

<details>
<summary>深讀：為什麼 Debug Mode 會要求你親自復現</summary>

很多 bug 不是“讀程式碼”能確認的，尤其是 timing、async、狀態競爭、效能和記憶體問題。Debug Mode 新增 instrumentation 後，需要你按步驟復現，讓日誌捕獲真實執行路徑。

這一步把使用者留在迴圈裡：Agent 負責假設和插樁，使用者負責觸發現象。最後的修復應該能被同一套復現步驟再次驗證。
</details>

## 6. 驗收清單

Debug Mode 結束前，至少檢查：

- 是否列出過多個假設，而不是直接改程式碼。
- 是否新增過必要 instrumentation。
- 是否由你按步驟復現過問題。
- 是否基於 logs、stack traces 或 runtime context 定位根因。
- 最終 diff 是否集中，避免擴散重構。
- 所有 instrumentation 是否已清理。
- 是否用同一套復現步驟驗證修復。
- 是否補了測試或留下手工驗證證據。

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Debug Mode 和 Agent Mode 的本質差別是什麼？
2. 為什麼 Debug Mode 需要復現步驟和執行時證據？
3. 修復完成後，為什麼必須清理 instrumentation？

透過標準：你能給一個疑難 bug 寫出 Debug Mode prompt，並能判斷最終修復是否真的來自 root cause，而不是猜測。

## 官方來源

- [Cursor Debug Mode](https://cursor.com/docs/agent/debug-mode.md) —— 官方說明適用場景、六步工作流、插樁、復現、日誌分析、修復和清理。
- [Cursor Help: Debug Mode](https://cursor.com/help/ai-features/debug-mode.md) —— Help Center 說明入口、模式差異和使用步驟。

## 接下來去哪

<Cards>
  <Card title="Agent Review" description="修復後繼續審查本地變更和風險。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/15-agent-review" />
  <Card title="Browser Tool" description="需要視覺復現時，繼續學習瀏覽器工具。" href="/zh-Hant/docs/cursor/official/01-agent-workflow/17-browser-tool" />
</Cards>
