Cursor官方：使用AI编程的最佳实践

最近，Cursor官方团队发布了一个Agent使用指南。

这篇文档来自 Cursor 团队自己如何使用 Cursor 的真实经验。读完后最大的感受是：大部分人对 AI 编程助手的理解都错了。

我们以为应该给 agent 塞满 context、写超长提示词、在一个对话里完成所有事情。

但 Cursor 团队的实践恰恰相反，他们强调克制、简化、分离关注点。这种反差让我意识到，使用 coding agent 需要一套完全不同的思维模式。

下面是这篇文章的主要内容。

感兴趣的可以阅读原文：

为什么计划比代码更重要

文档开篇就引用了芝加哥大学的研究发现：经验丰富的开发者更倾向于在生成代码之前先做计划。这个理论不新鲜，但 Cursor 把它变成了强制流程。

按 Shift+Tab 切换到 Plan Mode 后，agent 不会立即写代码，而是执行四个步骤：研究你的代码库找到相关文件、提出澄清性问题确认需求、创建包含文件路径和代码引用的详细计划、等待你的批准才开始构建。

计划会以 Markdown 文件形式打开，你可以直接编辑——删除不必要的步骤、调整实现方法、补充 agent 遗漏的 context。这些计划可以存到 .cursor/plans/ 作为团队文档，也方便恢复中断的工作。

真正有价值的是当 agent 跑偏时的处理方式。

Cursor 团队给出的建议完全反直觉：当 agent 构建的东西不符合预期时，不要试图通过后续提示修正它。应该直接撤销所有更改，回到计划，把计划改得更具体，然后重新运行。

这个建议之所以重要，是因为它揭示了 agent 工作的本质：agent 在执行它认为的计划。当执行方向错了，在错误的基础上修补只会越走越歪。重新规划往往比修补更快，代码质量也更高。

当然，不是每个任务都需要详细计划。对于快速改动或你做过很多次的重复任务，直接跳到 agent 就行。但对于复杂的多文件重构、新功能开发、或者你不太确定的任务，Plan Mode 能显著提高成功率。

关于上下文管理的认知偏差

大部分人用 agent 时会在提示词里手动 @ 一堆文件，生怕 agent 找不到需要的 context。

Cursor 团队说：你不需要这么做。

这听起来很简单，但背后的逻辑很深刻。Cursor 的 agent 配备了两套强大的搜索工具：grep（毫秒级搜索代码库）和语义搜索（理解概念而非字面匹配）。

当你在提示词里说"认证流程"，agent 会通过这两个工具找到相关文件，即使你的提示词里没有包含那些文件的确切名字。

原则很简单：如果你明确知道是哪个文件，就标记它。如果不知道，就让 agent 自己找。 包含太多不相关的文件反而会让 agent 困惑——它分不清哪些信息重要，哪些是噪音。

文档还提到了一个实用工具：@Branch。用"Review the changes on this branch"或"What am I working on?"这种自然语言，就能让 agent 理解你当前的工作 context。

更关键的问题是：什么时候应该开始新对话？

Cursor 团队给出了清晰的判断标准。转向不同的任务、agent 看起来困惑或不断犯同样的错误、完成了一个逻辑工作单元时，应该开始新对话。在同一功能上迭代、agent 需要对话早期的 context、正在调试它刚构建的东西时，可以继续对话。

这里有个容易被忽视的细节：长对话会导致 agent 失焦。 经过多轮对话和总结后，context 会积累噪音，agent 可能会分心或切换到无关任务。如果你发现 agent 的效果开始下降，就该开始新对话了。

那之前对话的信息怎么办？用 @Past Chats 引用历史对话，不要复制粘贴整个对话。Agent 会选择性地从历史中读取它需要的部分，这比复制整个对话效率高得多。

##Rules 和 Skills 的本质区别

Cursor 提供两种自定义 agent 行为的方式：Rules 和 Skills。大部分人搞不清楚它们的区别，导致用法混乱。

Rules 是静态 context，永远在场。

Rules 存储在 .cursor/rules/ 目录下的 Markdown 文件里。每次对话开始时，agent 都会看到这些规则。你应该在 Rules 里写：运行什么命令（npm run build、npm run test 等）、遵循什么模式（用 ES modules 而非 CommonJS、如何结构化组件等）、参考哪些示例文件（components/Button.tsx 是标准组件结构）。

关键是：引用文件，不要复制内容。 这样 Rules 保持简短，也不会因为代码变化而过时。

Cursor 团队明确指出要避免的三个坑：不要复制整个风格指南（应该用 linter）、不要记录每个可能的命令（agent 知道常用工具）、不要为极少出现的边缘情况添加指令。

核心原则是：只在看到 agent 重复犯同样错误时才添加 Rules。 不要在理解自己的使用模式之前就过度优化。

把 Rules 提交到 git，整个团队都能受益。当发现 agent 犯错时，更新 Rule。你甚至可以在 GitHub issue 或 PR 上 @ cursor，让 agent 自动更新 Rule。

Skills 是动态能力，按需加载。

Skills 定义在 SKILL.md 文件里，可以包含自定义命令（用 / 触发的可复用工作流）、Hooks（在 agent 动作前后运行的脚本）、领域知识（特定任务的专门指令）。

与 Rules 不同，Skills 只在 agent 认为相关时才会加载。这保持了 context 窗口的干净，同时给了 agent 访问专门能力的途径。

文档给出了一个强大的例子：用 Skills 创建长时间运行的 agent 循环，让它持续工作直到达成目标。通过在 .cursor/hooks.json 配置 hook，agent 可以在完成后检查是否达标，如果没有就继续迭代，直到所有测试通过或达到最大迭代次数。这个模式适用于运行测试并修复直到全部通过、迭代 UI 直到匹配设计稿、任何有可验证成功标准的目标导向任务。

四个立即可用的实战工作流

TDD 的正确姿势

文档详细描述了如何让 agent 做测试驱动开发。首先，要求 agent 基于预期的输入输出对编写测试，关键是明确告诉它你在做 TDD，这样它就不会为还不存在的功能创建 mock 实现。

其次，让 agent 运行测试并确认它们失败，明确说不要在这个阶段写实现代码。接着，对测试满意后提交它们。然后，要求 agent 编写能通过测试的代码，指示它不要修改测试，并持续迭代直到所有测试通过。最后，对实现满意后提交。

这个流程之所以有效，是因为 agent 在有明确目标可以迭代时表现最好。测试提供了清晰的成功标准，agent 可以做出改动、评估结果、逐步改进直到成功。

Git 工作流自动化

Agent 可以搜索 git 历史、解决合并冲突、自动化整个 git 工作流。文档给出了一个 /pr 命令的例子，展示了如何把多步骤流程打包成一个命令：用 git diff 查看更改、根据改动写 commit 消息、push 到当前分支、用 gh pr create 创建 PR、返回 PR URL。

这类命令适合每天运行多次的工作流。把它们存为 .cursor/commands/ 里的 Markdown 文件，提交到 git，整个团队都能用。Cursor 团队自己还用 /fix-issue 获取 issue 详情并实现修复、/review 运行 linters 检查问题、/update-deps 逐个更新依赖并运行测试。

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

并行运行多个模型

Cursor 让并行运行多个 agent 变得很简单，它们互不干扰。团队发现，让多个模型尝试同一问题并选择最佳结果，能显著改善最终输出，特别是对困难任务。

Cursor 会自动创建和管理 git worktrees 用于并行 agent。每个 agent 在自己的 worktree 中运行，有独立的文件和改动，所以它们可以编辑、构建、测试代码而不会互相踩踏。

一个强大的模式是从下拉菜单选择多个模型，提交同样的提示词，并排比较结果。Cursor 还会建议它认为最好的方案。这特别适用于困难问题、跨模型系列比较代码质量、发现某个模型可能遗漏的边缘情况。

Debug Mode 的独特价值

当标准 agent 交互难以解决某个 bug 时，Debug Mode 提供了完全不同的方法。

它会生成多个关于可能出错的假设、在代码中插入详细的日志语句、要求你重现 bug 同时收集运行时数据、分析实际行为找出根本原因、基于证据进行针对性修复。

这最适合你能重现但想不通的 bug、竞态条件和时序问题、性能问题和内存泄漏、曾经能用但现在不行的退化问题。关键是提供详细的重现步骤。你越具体，agent 添加的仪器化代码就越有用。

成功者的共同特质

文档最后总结了从 agents 获得最大价值的开发者的几个共同点。

他们写具体的提示词。Agent 的成功率随着指令的具体程度显著提高。对比"为 auth.ts 添加测试"和"为 auth.ts 编写测试用例，覆盖登出边缘情况，使用 __tests__/ 中的模式，避免 mocks"，第二个提示词的成功率要高得多。

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

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