---
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="/docs/cursor/official/01-agent-workflow/15-agent-review" />
  <Card title="Browser Tool" description="需要视觉复现时，继续学习浏览器工具。" href="/docs/cursor/official/01-agent-workflow/17-browser-tool" />
</Cards>
