Cursor Agent 最佳实践

编程 Agent 正在改变软件开发的方式。

如今，模型可以连续运行数小时，完成复杂的多文件重构，反复迭代直到测试通过。但要充分发挥 Agent 的潜力，你得理解它的工作原理，掌握新的使用模式。

本指南将介绍与 Cursor Agent 协作的技巧。不管你是刚接触 Agent 编程，还是想了解我们团队怎么用 Cursor，这里都能找到与 Agent 高效协作的方法。

理解 Agent 框架

Agent 框架（Agent harness）有三个核心部分：

1. 指令：引导 Agent 行为的系统提示词和规则
2. 工具：文件编辑、代码库搜索、终端执行等能力
3. 用户消息：你的提示词和后续指令

Cursor 为每个支持的模型协调这些组件。我们根据内部评估和外部基准测试，为每个前沿模型专门调优指令和工具。

为什么框架很重要？因为不同模型对相同提示词的响应方式不同。有的模型在 shell 工作流上训练较多，更习惯用 grep 而非专用搜索工具；有的模型则需要明确指令才会在编辑后调用 linter。Cursor 的 Agent 帮你处理这些差异——新模型发布时，你只管专注构建软件。

从计划开始

最能提升效果的改变就是：先计划，再编码。

芝加哥大学的一项研究发现，经验丰富的开发者更倾向于在生成代码前先做计划。计划迫使你想清楚要构建什么，也给 Agent 提供了明确的目标。

使用计划模式

在 Agent 输入框中按 Shift+Tab 切换计划模式（Plan Mode）。Agent 不会立即写代码，而是：

1. 研究你的代码库，找到相关文件
2. 询问澄清性问题，明确需求
3. 创建详细的实现计划，包含文件路径和代码引用
4. 等待你确认后再开始构建

计划模式实战：Agent 会询问澄清性问题，创建可审阅的计划。

计划会以 Markdown 文件形式打开，你可以直接编辑——删除不必要的步骤、调整方案，或补充 Agent 遗漏的上下文。

提示： 点击“保存到工作区”可将计划存储在 .cursor/plans/。这既能为团队留下文档，也便于恢复中断的工作，还能为后续处理同一功能的 Agent 提供上下文。

并非每个任务都需要详细计划。快速修改或你已经做过很多次的任务，直接用 Agent 就好。

从计划重新开始

有时 Agent 构建的东西与你期望的不符。与其通过追加提示词来修补，不如回到计划阶段。

撤销更改，细化计划使其更具体，然后重新运行。这通常比修正进行中的 Agent 更快，结果也更干净。

管理上下文

随着你对 Agent 写代码越来越熟悉，你的工作重心会转向：为每个 Agent 提供完成任务所需的上下文。

让 Agent 自己找上下文

不需要在提示词中手动标记每个文件。

Cursor 的 Agent 有强大的搜索工具，可以按需拉取上下文。当你询问“认证流程”时，Agent 会通过 grep 和语义搜索找到相关文件，哪怕你的提示词里没有那些确切的词。

即时 grep 让 Agent 能在毫秒内搜索你的代码库。

简单点说：知道确切文件就标记它，不知道就让 Agent 自己找。包含无关文件反而会让 Agent 困惑，分不清什么是重点。

Cursor 的 Agent 还有一些实用工具，比如 @Branch，可以告诉 Agent 你当前在做什么。“审查这个分支的更改”或“我在做什么？”就能让 Agent 快速了解当前任务。

何时开始新对话

最常见的问题之一：继续当前对话还是开始新的？

开始新对话的情况：

• 转向不同的任务或功能
• Agent 看起来很困惑或反复犯同样的错误
• 完成了一个逻辑工作单元

继续当前对话的情况：

• 在同一个功能上迭代
• Agent 需要之前讨论的上下文
• 正在调试它刚构建的东西

长对话会让 Agent 失去焦点。经过多轮对话和摘要后，上下文会累积噪音，Agent 可能会分心或转向不相关的任务。如果你发现 Agent 效率在下降，就该开始新对话了。

引用过去的工作

开始新对话时，用 @Past Chats 引用之前的工作，而不是复制粘贴整个对话。Agent 会从聊天历史中挑选需要的上下文。

这比复制整个对话高效得多。

引用过去的聊天，从之前的对话中引入上下文

扩展 Agent

Cursor 提供两种主要方式来定制 Agent 行为：规则（Rules） 用于每次对话都适用的静态上下文，技能（Skills） 用于 Agent 在需要时可以使用的动态能力。

规则提供持久性指令，塑造 Agent 与你代码的协作方式。可以理解为每次对话都会加载的固定上下文。

在 .cursor/rules/ 中创建包含 RULE.md 文件的文件夹：

# 命令

- `npm run build`: 构建项目
- `npm run typecheck`: 运行类型检查
- `npm run test`: 运行测试（为了速度，优先测试单个文件）

# 代码风格

- 使用 ES 模块（import/export），不用 CommonJS（require）
- 尽可能使用解构导入：`import { foo } from 'bar'`
- 参考 `components/Button.tsx` 了解标准组件结构

# 工作流

- 在进行一系列代码更改后，始终进行类型检查
- API 路由放在 `app/api/`，遵循现有模式

规则要抓住重点：该跑什么命令、该遵循什么模式、代码库中有哪些典型示例。引用文件就好，别复制内容——这样规则既简短，又不会因代码变化而过时。

规则中要避免的：

• 复制整个风格指南（用 linter 代替）
• 记录每个可能的命令（Agent 知道常用工具）
• 为很少出现的边缘情况添加指令

提示： 从简单开始。只在发现 Agent 反复犯同样错误时才添加规则。在理解你的模式之前，不要过度优化。

把规则提交到 git，让整个团队受益。发现 Agent 犯错时就更新规则。你甚至可以在 GitHub issue 或 PR 中 @cursor，让 Agent 帮你更新规则。

技能：动态能力和工作流

Agent 技能扩展了 Agent 的能力范围。技能打包了领域特定的知识、工作流和脚本，Agent 可以在需要时调用。

技能定义在 SKILL.md 文件中，可以包括：

• 自定义命令：在 Agent 输入框中用 / 触发的可复用工作流
• 钩子（Hooks）：在 Agent 操作前后运行的脚本
• 领域知识：Agent 可以按需拉取的特定任务指令

与始终包含的规则不同，技能在 Agent 判断需要时才会动态加载。这既保持了上下文窗口的整洁，又让 Agent 能使用专业能力。

示例：长时间运行的 Agent 循环

一个强大的模式是用技能创建持续运行的 Agent，不断迭代直到达成目标。以下是如何构建一个让 Agent 持续工作直到所有测试通过的钩子。

首先，在 .cursor/hooks.json 中配置钩子：

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

钩子脚本（.cursor/hooks/grind.ts）从 stdin 接收上下文，返回 followup_message 继续循环：

import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();

const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message: `[迭代 ${input.loop_count + 1}/${MAX_ITERATIONS}] 继续工作。完成后在 .cursor/scratchpad.md 中标记 DONE。`
  }));
}

这个模式适合：

• 运行（并修复）直到所有测试通过
• 迭代 UI 直到匹配设计稿
• 任何成功可验证的目标导向任务

提示： 带钩子的技能可以与安全工具、密钥管理器和可观测性平台（如监控、日志系统）集成。参见钩子文档了解合作伙伴集成。

Agent 技能目前仅在 nightly 发布渠道可用。打开 Cursor 设置，选择 Beta，将更新渠道设为 Nightly，然后重启。

除了编程，你还可以把 Agent 连接到日常使用的其他工具。MCP（模型上下文协议）让 Agent 能读取 Slack 消息、调查 Datadog 日志、从 Sentry 调试错误、查询数据库等。

包含图片

Agent 可以直接处理提示词中的图片。粘贴截图、拖入设计文件，或引用图片路径。

设计转代码

粘贴设计稿，让 Agent 实现它。Agent 能看到图片，可以匹配布局、颜色和间距。你也可以用 Figma MCP 服务器。

可视化调试

截图显示错误状态或意外的 UI，让 Agent 调查。这通常比用文字描述问题更快。

Agent 还能控制浏览器来自己截图、测试应用、验证视觉变化。详见浏览器文档。

浏览器侧边栏让你能同时进行设计和编码。

常见工作流

以下是在不同类型任务中效果良好的 Agent 模式。

测试驱动开发

Agent 可以自动写代码、运行测试、迭代：

1. 让 Agent 根据预期输入/输出编写测试。明确说明你在做 TDD，这样它就不会为还不存在的功能创建 mock 实现。
2. 让 Agent 运行测试并确认失败。明确说明此阶段不要写实现代码。
3. 测试满意后提交。
4. 让 Agent 写代码通过测试，指示它不要修改测试。告诉它持续迭代直到所有测试通过。
5. 对更改满意后提交实现。

Agent 在有明确迭代目标时表现最好。测试让 Agent 能做出更改、评估结果，逐步改进直到成功。

理解代码库

接手新代码库时，用 Agent 来学习和探索。问它你会问同事的问题：

• “这个项目的日志是怎么工作的？”
• “如何添加新的 API 端点？”
• “CustomerOnboardingFlow 处理了哪些边缘情况？”
• “为什么第 1738 行调用 setUser() 而不是 createUser()？”

Agent 同时使用 grep 和语义搜索来浏览代码库并找到答案。这是快速熟悉陌生代码最有效的方式之一。

Git 工作流

Agent 可以搜索 git 历史、解决合并冲突、自动化你的 git 工作流。

例如，一个提交、推送并打开 PR 的 /pr 命令：

为当前更改创建 pull request。

1. 用 `git diff` 查看暂存和未暂存的更改
2. 根据更改内容写一条清晰的提交消息
3. 提交并推送到当前分支
4. 用 `gh pr create` 打开带标题和描述的 pull request
5. 完成后返回 PR URL

命令适合你每天运行多次的工作流。把它们作为 Markdown 文件存储在 .cursor/commands/，提交到 git，让整个团队都能使用。

我们使用的其他命令示例：

• /fix-issue [number]：用 gh issue view 获取 issue 详情，找到相关代码，实现修复，然后打开 PR
• /review：运行 linter，检查常见问题，总结需要关注的地方
• /update-deps：检查过时的依赖，逐个更新，每次更新后运行测试

Agent 可以自主使用这些命令，让你用一个 / 调用就能委托多步骤工作流。

审查代码

AI 生成的代码需要审查，Cursor 提供了多种选项。

生成过程中

观察 Agent 工作。diff 视图实时显示更改。如果你发现 Agent 走偏了，按 Escape 中断并重新引导。

Agent 审查

Agent 完成后，点击 Review → Find Issues 运行专门的审查流程。Agent 逐行分析提议的编辑，标记潜在问题。

对于所有本地更改，打开 Source Control 标签页，运行 Agent Review 与主分支对比。

AI 代码审查能直接在 Cursor 中发现并修复 bug。

Pull Request 的 Bugbot

推送到代码仓库，在 PR 上获得自动审查。Bugbot 运用高级分析，在每个 PR 上尽早发现问题并提出改进建议。

架构图

对于重大更改，让 Agent 生成架构图。试试这样提示：“创建一个 Mermaid 图，展示我们认证系统的数据流，包括 OAuth 提供商、会话管理和令牌刷新。”这些图对文档很有用，还能在代码审查前发现架构问题。

并行运行多个 Agent

Cursor 让你轻松并行运行多个 Agent，互不干扰。我们发现，让多个模型尝试同一问题，然后选择最佳结果，能显著提升最终输出质量，尤其是较难的任务。

原生工作树支持

Cursor 自动为并行 Agent 创建和管理 git 工作树（worktrees）。每个 Agent 在自己的工作树中运行，拥有独立的文件和更改，因此 Agent 可以编辑、构建和测试代码，互不影响。

要在工作树中运行 Agent，从 Agent 下拉菜单中选择工作树选项。Agent 完成后，点击 Apply 将更改合并回你的工作分支。

同时运行多个模型

一个强大的模式是同时用多个模型运行同一个提示词。从下拉菜单中选择多个模型，提交提示词，并排比较结果。Cursor 还会推荐它认为最佳的方案。

多 Agent 评判显示 Cursor 推荐的方案

适合以下场景：

• 不同模型可能采取不同方法的难题
• 跨模型家族比较代码质量
• 发现单个模型可能遗漏的边缘情况

并行运行多个 Agent 时，配置通知和声音，以便知道它们何时完成。

委托给云端 Agent

云端 Agent 适合那些你本来会加到待办清单的任务：

• 处理其他事情时发现的 bug 修复
• 最近代码更改的重构
• 为现有代码生成测试
• 文档更新

你可以根据任务在本地和云端 Agent 之间切换。从 cursor.com/agents、Cursor 编辑器或手机启动云端 Agent。离开电脑时，从网页或手机检查会话状态。云端 Agent 运行在远程沙箱中，你可以合上笔记本电脑，稍后查看结果。

从 cursor.com/agents 管理多个云端 Agent

云端 Agent 的工作原理：

1. 描述任务和相关上下文
2. Agent 克隆你的仓库并创建分支
3. 自主工作，完成后打开 PR
4. 完成时通知你（通过 Slack、邮件或网页界面）
5. 审查更改，准备好后合并

提示： 你可以在 Slack 中用“@Cursor”触发 Agent。了解更多。

棘手 bug 的调试模式

当常规 Agent 交互难以解决 bug 时，调试模式（Debug Mode）提供了另一种方法。

调试模式不是猜测修复方案，而是：

1. 生成多个关于可能出错的假设
2. 在你的代码中插入日志语句
3. 让你重现 bug，同时收集运行时数据
4. 分析实际行为以定位根本原因
5. 基于证据进行针对性修复

Agent 下拉菜单中的调试模式

最适合以下情况：

• 你能重现但搞不清楚的 bug
• 竞态条件和时序问题
• 性能问题和内存泄漏
• 某些功能曾经正常但现在不行的回归问题

关键是提供如何重现问题的详细上下文。你描述得越具体，Agent 添加的日志就越有用。

发展你的工作流

真正用好 Agent 的开发者有几个共同点：

他们写具体的提示词。 具体的指令能显著提高 Agent 的成功率。比较一下“为 auth.ts 添加测试”和“为 auth.ts 写一个测试用例，覆盖登出边缘情况，使用 __tests__/ 中的模式，避免 mock。”

他们持续迭代配置。 从简单开始。只在发现 Agent 反复犯同样错误时才添加规则。只在摸索出想要重复的工作流后才添加命令。在理解你的模式之前，不要过度优化。

他们仔细审查。 AI 生成的代码可能看起来正确但实际有微妙的错误。阅读 diff，仔细审查。Agent 工作得越快，你的审查流程就越重要。

他们提供可验证的目标。 Agent 不知道的问题就无法修复。使用类型化语言，配置 linter，编写测试。给 Agent 明确的信号来判断更改是否正确。

他们把 Agent 当作有能力的协作者。 要求制定计划，请求解释，对不喜欢的方法提出异议。

Agent 正在快速进步。虽然这些模式会随着新模型的发展而演变，但我们希望这些内容能帮助你在今天与编程 Agent 协作时更加高效。

开始使用 Cursor Agent 来尝试这些技巧。