发布于 2026年1月20日

译：使用 Agent 编程的最佳实践

原文：https://cursor.com/blog/agent-best-practices
作者：Cursor Team
译者：Claude Opus 4.5

编程 Agent 正在改变软件的构建方式。

模型现在可以运行数小时，完成雄心勃勃的多文件重构，并不断迭代直到测试通过。但要充分发挥 Agent 的作用，需要理解它们的工作原理并开发新的模式。

本指南涵盖了使用 Cursor Agent 的技术。无论你是 Agent 编程的新手，还是想了解我们团队如何使用 Cursor，我们都将介绍使用 Agent 编程的最佳实践。

#理解 Agent 运行环境 (Harness)

Agent 运行环境由三个组件构建而成：

指令 (Instructions)：引导 Agent 行为的系统提示词和规则
工具 (Tools)：文件编辑、代码库搜索、终端执行等
用户消息 (User messages)：指导工作的提示词和后续跟进

Cursor 的 Agent 运行环境为我们支持的每个模型编排这些组件。我们根据内部评估和外部基准，专门为每个前沿模型微调指令和工具。

运行环境之所以重要，是因为不同的模型对相同提示词的反应不同。一个经过大量 shell 工作流训练的模型可能更喜欢 grep 而不是专门的搜索工具。另一个模型可能需要在编辑后显式指令来调用 linter 工具。Cursor 的 Agent 会为你处理这些，因此随着新模型的发布，你可以专注于构建软件。

#从计划开始

你能做出的最有影响力的改变就是在编码前进行计划。

芝加哥大学的一项研究发现，经验丰富的开发人员更有可能在生成代码之前进行计划。计划迫使你清晰地思考正在构建的内容，并为 Agent 提供具体的工作目标。

#使用计划模式 (Plan Mode)

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

研究你的代码库以找到相关文件
针对你的需求提出澄清问题
创建包含文件路径和代码引用的详细实施计划
在开始构建前等待你的批准

计划模式实战：Agent 提出澄清问题并创建一个可审查的计划。

计划以 Markdown 文件形式打开，你可以直接编辑以删除不必要的步骤、调整方法或添加 Agent 遗漏的内容。

提示： 点击 “Save to workspace” 将计划存储在 .cursor/plans/ 中。这可以为你的团队创建文档，方便恢复中断的工作，并为将来处理同一功能的 Agent 提供背景信息。

并非每个任务都需要详细的计划。对于快速更改或你已经做过多次的任务，直接交给 Agent 处理即可。

#从计划重新开始

有时 Agent 构建的内容不符合你的预期。与其尝试通过后续提示词来修复它，不如回到计划。

撤销更改，改进计划以更具体地说明你的需求，然后再次运行。这通常比修复进行中的 Agent 更快，并且能产生更整洁的结果。

#管理上下文

随着你越来越习惯让 Agent 编写代码，你的工作变成了为每个 Agent 提供完成任务所需的上下文。

#让 Agent 寻找上下文

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

Cursor 的 Agent 拥有强大的搜索工具，并按需获取上下文。当你询问 “身份验证流程 (authentication flow)” 时，Agent 会通过 grep 和语义搜索找到相关文件，即使你的提示词中没有包含这些确切的词。

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

保持简单：如果你知道确切的文件，就标记它。如果不知道，Agent 会找到它。包含无关文件可能会让 Agent 混淆重点。

Cursor 的 Agent 还有一些有用的工具，比如 @Branch，它可以让你向 Agent 提供关于你正在处理的任务的上下文。"检查此分支上的更改"或"我正在处理什么？"成为引导 Agent 了解你当前任务的自然方式。

#何时开始新对话

一个最常见的问题：我是应该继续这段对话，还是重新开始？

在以下情况下开始新对话：

你正在转向不同的任务或功能
Agent 似乎感到困惑或一直犯同样的错误
你已经完成了一个逻辑单元的工作

在以下情况下继续对话：

你正在迭代同一个功能
Agent 需要讨论早期的上下文
你正在调试它刚刚构建的内容

漫长的对话会导致 Agent 失去焦点。经过多次往返和总结，上下文会积累噪声，Agent 可能会分心或转向无关任务。如果你注意到 Agent 的效率下降，那就是时候开始新对话了。

#引用过去的工作

当你开始新对话时，使用 @Past Chats 来引用之前的工作，而不是复制粘贴整个对话。Agent 可以有选择地从聊天记录中读取内容，只拉取它需要的上下文。

这比复制整个对话更有效率。

Reference past chats to bring in context from previous conversations

#扩展 Agent

Cursor 提供了两种自定义 Agent 行为的主要方式：适用于每个对话的静态上下文 Rules (规则)，以及 Agent 在相关时可以使用的动态能力 Skills (技能)。

#Rules：项目的静态上下文

Rules 提供了持久的指令，塑造了 Agent 处理代码的方式。可以将它们视为 Agent 在每次对话开始时都会看到的"常驻"上下文。

在 .cursor/rules/ 中将规则创建为 markdown 文件：

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

让规则专注于核心：要运行的命令、要遵循的模式以及指向代码库中典型示例的指针。引用文件而不是复制其内容；这样可以保持规则简短，并防止它们随着代码更改而过时。

Rules 中应避免的内容：

复制整个代码规范指南（请改用 linter）
记录每个可能的命令（Agent 了解常用工具）
为极少出现的边缘情况添加指令

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

将你的规则提交到 git，以便整个团队受益。当你看到 Agent 犯错时，更新规则。你甚至可以在 GitHub issue 或 PR 上标记 @cursor，让 Agent 为你更新规则。

#Skills：动态能力和工作流

Agent Skills 扩展了 Agent 的能力。Skills 封装了特定领域的知识、工作流和脚本，Agent 可以在相关时调用。

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

自定义命令：在 Agent 输入中使用 / 触发的可重用工作流
钩子 (Hooks)：在 Agent 操作之前或之后运行的脚本
领域知识：Agent 可以按需拉取的针对特定任务的指令

与始终包含的 Rules 不同，Skills 是在 Agent 决定它们相关时动态加载的。这保持了你的上下文窗口整洁，同时让 Agent 能够访问专业能力。

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

一个强大的模式是使用 Skills 来创建长时间运行的 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: `[Iteration ${
        input.loop_count + 1
      }/${MAX_ITERATIONS}] Continue working. Update .cursor/scratchpad.md with DONE when complete.`,
    })
  );
}

这种模式适用于：

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

提示： 带有钩子的 Skills 可以与安全工具、密钥管理器和可观察性平台集成。有关合作伙伴集成，请参阅 hooks 文档。

Agent Skills 目前仅在 nightly 发布渠道中提供。打开 Cursor 设置，选择 Beta，然后将更新渠道设置为 Nightly 并重启。

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

#包含图像

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

#设计转代码

粘贴设计原型图，让 Agent 实现它。Agent 能看到图像并匹配布局、颜色和间距。你也可以使用 Figma MCP server。

#视觉调试

对错误状态或非预期的 UI 进行截图，让 Agent 进行调查。这通常比用语言描述问题更快。

Agent 还可以控制浏览器进行截图、测试应用程序并验证视觉更改。详情请参阅 Browser 文档。

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

#常用工作流

以下是适用于不同类型任务的 Agent 模式。

#测试驱动开发 (TDD)

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

让 Agent 根据预期的输入/输出对编写测试。明确告诉它你正在进行 TDD，这样它就会避免为尚不存在的功能创建模拟实现。
告诉 Agent 运行测试并确认测试失败。明确要求它在此阶段不要编写实现代码。
对测试满意后，提交这些测试。
让 Agent 编写通过测试的代码，并指示它不要修改测试。告诉它持续迭代，直到所有测试通过。
对更改满意后，提交实现代码。

当 Agent 有明确的迭代目标时，表现最好。测试允许 Agent 进行更改、评估结果并逐步改进，直到成功。

#理解代码库

在熟悉新代码库时，利用 Agent 进行学习和探索。问它一些你会问同事的问题：

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

Agent 使用 grep 和语义搜索来查看代码库并找到答案。这是快速上手陌生代码的最快方法之一。

#Git 工作流

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

例如，一个 /pr 命令，用于提交、推送并开启 pull request：

Create a pull request for the current changes.

1. Look at the staged and unstaged changes with `git diff`
2. Write a clear commit message based on what changed
3. Commit and push to the current branch
4. Use `gh pr create` to open a pull request with title/description
5. Return the PR URL when done

对于每天运行多次的工作流，使用命令是理想的选择。将它们作为 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 requests 的 Bugbot

推送到源代码控制系统，以获得 pull requests 的自动审查。Bugbot 应用高级分析，尽早发现问题并在每个 PR 上提出改进建议。

#架构图

对于重大更改，可以让 Agent 生成架构图。尝试提示：“创建一个 Mermaid 图表，显示我们身份验证系统的数据流，包括 OAuth 提供程序、会话管理和令牌刷新。”这些图表对于文档很有用，并且可以在代码审查之前发现架构问题。

#并行运行 Agent

Cursor 让你能够轻松地并行运行多个 Agent，而不会互相干扰。我们发现，让多个模型尝试解决同一个问题并从中选择最佳结果，可以显著提高最终输出的质量，尤其是对于较难的任务。

#原生 worktree 支持

Cursor 为并行运行的 Agent 自动创建并管理 git worktrees。每个 Agent 在各自的 worktree 中运行，文件和更改相互隔离，因此 Agent 可以编辑、构建和测试代码，而不会互相干扰。

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

#同时运行多个模型

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

Multi-agent judging shows which solution Cursor recommends

这对于以下情况特别有用：

不同模型可能采取不同方法的难题
比较不同模型系列的代码质量
发现一个模型可能遗漏的边缘情况

当并行运行多个 Agent 时，请配置通知和声音，以便你了解它们何时完成。

#委派给云端 Agent (Cloud Agents)

云端 Agent 非常适合处理你本来会添加到待办事项列表中的任务：

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

你可以根据任务在本地和云端 Agent 之间切换。从 cursor.com/agents、Cursor 编辑器或手机启动云端 Agent。当你离开座位时，可以通过网页或手机查看会话。云端 Agent 在远程沙盒中运行，因此你可以合上电脑，稍后再查看结果。

Kanban view of Cursor Agents performing coding and research tasks.

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

以下是云端 Agent 的底层工作原理：

描述任务和任何相关的上下文
Agent 克隆你的仓库并创建一个分支
它自主工作，完成后开启一个 pull request
完成后你会收到通知（通过 Slack、电子邮件或网页界面）
审查更改并在准备好时合并

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

#用于棘手 bug 的调试模式 (Debug Mode)

当标准 Agent 交互难以解决某个 bug 时，调试模式提供了一种不同的方法。

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

生成关于可能出现问题的多个假设
在代码中插入日志语句（插桩）
要求你复现 bug，同时收集运行时数据
分析实际行为以精确定位根本原因
基于证据进行针对性修复

Debug Mode in the agent dropdown

这最适用于：

你可以复现但无法理解的 bug
竞态条件和时序问题
性能问题和内存泄漏
以前正常工作但现在出现的回退问题 (Regressions)

关键是提供关于如何复现问题的详细上下文。你提供的越具体，Agent 添加的插桩就越有用。

#建立你的工作流

从 Agent 中获益最多的开发人员通常具备以下几个特质：

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

他们不断迭代配置。 从简单开始。只有当你注意到 Agent 反复犯同样的错误时，才添加规则。只有在你确定了想要重复的工作流后，才添加命令。在了解你的模式之前，不要过度优化。

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

他们提供可验证的目标。 Agent 无法修复它不知道的问题。使用静态类型语言，配置 linter 并编写测试。为 Agent 提供关于更改是否正确的清晰信号。

他们将 Agent 视为有能力的合作者。 索要计划。请求解释。拒绝你不喜欢的方法。

Agent 正在飞速改进。虽然模式会随着新模型的出现而演变，但我们希望这些能帮助你在今天使用编程 Agent 时更具生产力。

立即开始使用 Cursor’s agent 来尝试这些技术。

Author: Cursor Team