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 说明入口、模式差异和使用步骤。