33 · 最佳实践

Cursor 使用锦囊：从入门到精通的实战指南

目录

1. 引言：为什么需要最佳实践
2. Prompt 工程 — 与 AI 对话的核心技能
3. AI 层的选择策略
4. 提交策略与 AI 协作
5. 上下文管理
6. 项目规则（.cursorrules）
7. AI 代码审查
8. 团队工作流模式
9. 效率最大化技巧
10. 总结与下一步

01 · 引言：为什么需要最佳实践

Cursor 不是普通的编辑器。它是一个 AI-native 的开发环境，将大语言模型深度嵌入编码流程的每一个环节。但工具再强大，使用方式决定最终产出。

没有最佳实践的常见结果：

本文从实战出发，提炼 9 个核心维度的最佳实践。每个实践都配有 正面示例 与 反面教材，帮助你在日常开发中直接应用。

02 · Prompt 工程 — 与 AI 对话的核心技能

Prompt 是人与 AI 之间最直接的接口。写好 Prompt，Cursor 的输出质量会成倍提升。

2.1 结构化 Prompt 模板

一个好的 Prompt 应当包含四个要素：

[角色]     → 你是一个资深 React 工程师
[上下文]   → 我们使用 Next.js 14，App Router，TypeScript
[任务]     → 实现一个带搜索和分页的用户列表组件
[约束]     → 使用 Server Component + 客户端搜索，不要引入第三方 UI 库

正面示例：

你是一个熟悉 TanStack Query 的前端工程师。项目使用 React 18、TypeScript、Vite。请实现一个 useProducts hook，支持分页和条件过滤。使用 @tanstack/react-query 的 useInfiniteQuery。不需要 UI 层，只返回 hook 和数据类型定义。

反面教材：

写一个产品列表页面。

为什么反面教材不好？AI 不知道你用哪个框架、是否需要分页、状态管理方案是什么。生成的代码大概率要大改。

2.2 指定输出格式

明确告诉 AI 你想要的输出结构：

请按以下格式输出：
1. 类型定义（interface / type）
2. 核心逻辑函数
3. React 组件
4. 样式模块

2.3 迭代式 Prompt

不要期望一次 Prompt 得到完美代码。采用迭代策略：

第 1 轮：生成基础结构
第 2 轮：补充错误处理
第 3 轮：添加性能优化
第 4 轮：补充测试用例

每次聚焦一个关注点，AI 的输出质量更可控。

2.4 反面示例集

03 · AI 层的选择策略

Cursor 提供多个 AI 层：Cursor Tab（补全）、Ctrl+K（内联编辑）、Chat（对话）、Composer（多文件编辑）、Agent（自主执行）。每个层的定位不同，选错层是新手最常见的效率杀手。

3.1 各层能力对比

3.2 选择原则

原则一：能用低层不用高层

• 改一个函数名 → Tab 补全
• 重构一个函数 → Ctrl+K
• 理解一段逻辑 → Chat
• 新增一个页面 → Composer
• 跨文件搜索+修改+运行 → Agent

原则二：Agent 是最后手段

Agent 会自主读取文件、执行命令、修改多文件。它的自主性意味着不可预测性。应该先用 Chat 或 Composer 规划，确认方案后再执行。

3.3 实战对照

场景：给一个 API 路由添加请求参数校验

• ❌ 直接打开 Agent，说 “给所有 API 路由加校验” → Agent 可能改了大量不该改的文件
• ✅ 用 Chat 问 “这个项目用什么校验库？当前 API 路由的文件在哪？” → 了解上下文
• ✅ 用 Composer 打开目标文件，指定添加 zod 校验 → 精确修改

3.4 组合使用策略

最高效的工作流是组合使用：

1. Chat 探索 → 理解代码库结构
2. Ctrl+K 编辑 → 修改具体函数
3. Composer 编排 → 多文件协调
4. Agent 执行 → 运行测试/安装依赖
5. Tab 补全 → 日常编码

04 · 提交策略与 AI 协作

版本控制是开发的基础设施。与 AI 协作时代，提交策略需要重新思考。

4.1 原子提交原则

每次提交应当只包含一个逻辑变更。这在与 AI 协作时尤其重要：

• 回滚精确：AI 可能产生副作用，原子提交让你只回滚出问题的部分
• 审查清晰：PR review 时可以逐提交理解 AI 的改动
• 上下文纯净：每个提交的 diff 小，容易让 AI 理解变更意图

4.2 AI 辅助消息编写

Cursor 的 Chat 可以帮你生成提交消息：

请为以下变更生成一个符合 Conventional Commits 规范的提交消息： [粘贴 diff] 格式：type(scope): description

4.3 工作流：AI 编辑 → 审查 → 提交

1. AI 修改代码
2. 人工审查 diff（Ctrl+Shift+G）
3. 确认无误后分段提交
4. 让 AI 写提交消息
5. 手动调整后推送

不要这样做：

• 让 AI 连续改 10 个文件后一次性提交 → diff 太大，无法审查
• 不审查 AI 代码直接提交 → 风险极高
• 提交消息写 “fix bug” → 无法追溯

4.4 分支策略

使用 AI 进行实验性修改时，建议创建专属分支：

git checkout -b experiment/ai-refactor-auth

这样即使 AI 的修改不理想，主分支不会受到污染。

05 · 上下文管理

Cursor 的 AI 上下文窗口有限。管理好上下文 = 管理好 AI 的理解能力。

5.1 @ 引用系统

Cursor 提供了强大的 @ 引用机制，帮助 AI 获取精确上下文：

5.2 上下文精简策略

好实践： 只把相关代码加入上下文

❌ 把整个项目加入上下文 → Token 暴增，AI 注意力分散
✅ @引用关键文件（类型定义、工具函数、目标组件）

好实践： 使用 @file 指定具体文件，而非描述路径

❌ "在 src 目录下有个 api 文件夹，里面有个 client.ts 文件..."
✅ @/src/api/client.ts "这个文件中的 createClient 函数"

5.3 Checkpoint 机制

Composer 的 Checkpoint 功能可以保存每次 AI 修改的快照：

• 每次 AI 修改后，创建一个 Checkpoint
• 如果后续 AI 修改出现问题，可以直接回滚到 Checkpoint
• 比 Git 更精细，适合 AI 修改的快速实验

5.4 Notepad 长期记忆

Notepad 是 Cursor 的持久化上下文机制，适合存放：

• 项目架构说明
• 编码规范
• 常用的 Prompt 模板
• 团队约定

# Notepad: 项目上下文
 
## 技术栈
- Next.js 15 (App Router)
- Prisma ORM
- PostgreSQL
- Tailwind CSS
 
## 命名规范
- 组件：PascalCase
- 函数：camelCase
- 文件：kebab-case
 
## 目录结构
/src
  /app    → 路由页面
  /lib    → 工具函数
  /db     → 数据库操作
  /components → 可复用组件

在 Prompt 中引用 Notepad：@Notepad 项目上下文

06 · 项目规则（.cursorrules）

.cursorrules 文件是 Cursor 的”性格设定”。它告诉 AI 你的项目偏好、技术栈和编码约定。

6.1 规则文件结构

根目录下的 .cursorrules 对所有文件生效。你也可以在子目录放置 .cursorrules 实现局部覆盖。

6.2 完整规则模板

你是一个经验丰富的全栈工程师，精通 TypeScript、React、Next.js。
 
## 技术栈
- 框架：Next.js 15 (App Router)
- 语言：TypeScript (strict mode)
- 数据库：Prisma + PostgreSQL
- 样式：Tailwind CSS
- 状态管理：Zustand
- API 调用：TanStack Query
 
## 编码规范
1. 所有组件默认使用 Server Component
2. 只在需要交互时使用 "use client"
3. 使用 `cn()` 工具函数合并 Tailwind 类名
4. 错误边界使用 `error.tsx` 文件
5. 数据获取在 Server Component 中完成
6. API 路由使用 Next.js Route Handlers
7. 数据库查询使用 Prisma，在 Server Action 或 Route Handler 中调用
 
## 命名约定
- 组件文件：PascalCase.tsx
- 工具函数：camelCase.ts
- 类型定义：放在 `types/` 目录
- 数据库模型：Prisma schema 中 snake_case
 
## 组件样式
- 优先使用 Tailwind 原子类
- 复杂组件使用 `@layer components` 提取
- 不使用 CSS Modules 或 styled-components
 
## 需要避免的
- 不要使用 `any` 类型
- 不要在 Server Component 中使用 `useEffect`
- 不要直接在客户端调用 Prisma

6.3 规则反例

太模糊：

写好看的代码。

太宽泛：

用最好的实践。注意性能和安全。

有效的规则是具体的、可执行的、有正反例的。

6.4 团队共享规则

将 .cursorrules 纳入版本控制，团队所有成员共享同一套规则：

git add .cursorrules
git commit -m "chore: add cursor rules for team consistency"

每次技术栈升级或规范变更时，同步更新规则文件。

07 · AI 代码审查

将 AI 作为代码审查的助手，可以大幅提升审查效率和质量。

7.1 审查流程

开发者提交 PR
    ↓
AI 进行初步审查（代码质量、安全漏洞、性能问题）
    ↓
人类审查者关注架构和设计（AI 的弱点）
    ↓
AI 生成审查摘要
    ↓
合并或要求修改

7.2 审查 Prompt 模板

@git diff main...HEAD
 
请审查以上变更，重点关注：
1. 是否存在安全漏洞（SQL 注入、XSS、权限绕过）
2. 是否有性能问题（不必要的重复计算、内存泄漏）
3. 是否有 TypeScript 类型安全隐患
4. 是否符合项目的编码规范
 
对每个问题，请给出：
- 问题所在文件和行号
- 问题类型
- 修复建议
- 优先级（critical / major / minor）

7.3 审查层次

7.4 不要做什么

• 不要让 AI 做最终决定：AI 的建议只是参考，合并按钮在人类手中
• 不要完全依赖 AI 审查：AI 会忽略业务逻辑错误和架构问题
• 不要在审查前不提供上下文：给 AI 足够的背景信息才能得到有价值的审查

08 · 团队工作流模式

Cursor 在单人开发中表现出色，在团队协作中则需要额外的约定和流程。

8.1 统一配置文件

团队级别的配置文件：

.claude/settings.json       → Claude Code 配置
.claude/settings.local.json  → 个人覆盖（.gitignore）
.cursorrules                → 项目规则（版本控制）
.editorconfig               → 编辑器基础配置

8.2 AI 协作契约

团队应共同约定：

1. 谁可以运行 Agent 模式：Agent 可以修改文件，需明确权限
2. AI 修改的标记方式：在 commit message 中标注 [AI] 前缀
3. AI 生成代码的审查标准：所有 AI 代码必须经过人工 review
4. 规则文件的更新流程：修改 .cursorrules 需要团队讨论

8.3 Code Review 分工

8.4 共享 Prompt 库

团队可以建立一个 Prompt 仓库，存放常用场景的 Prompt 模板：

prompts/
├── api-route.md           # 新建 API 路由
├── database-migration.md  # 数据库迁移
├── component-template.md  # 组件模板
├── test-generation.md     # 测试生成
└── code-review.md         # 代码审查

在 Cursor 中引用这些模板：@/prompts/api-route.md

09 · 效率最大化技巧

9.1 键盘快捷键速查

9.2 Cursor Tab 高级用法

多行补全： 在函数体内换行，Cursor 可以预测并生成整个函数体。

条件补全： 写注释描述下一步操作，Cursor 会根据注释补全代码：

// 将用户列表按角色分组
// ↓ Cursor 自动补全
const groupedUsers = users.reduce((acc, user) => {
  acc[user.role] = acc[user.role] || [];
  acc[user.role].push(user);
  return acc;
}, {} as Record<string, User[]>);

Tab 拒绝： 按 Esc 拒绝不需要的补全，Cursor 会学习你的偏好。

9.3 Ctrl+K 效率技巧

• 选中 → Ctrl+K → 输入指令：针对选中代码的精确修改
• 不选中 → Ctrl+K → 输入指令：在当前光标位置生成新代码
• 使用 / 命令：/fix 修复问题，/explain 解释代码，/test 生成测试

9.4 上下文窗口管理

Context Window 是有限的资源，需要精打细算：

9.5 心智模型：AI 是你的高级实习生

将 Cursor 理解为 高级实习生，而不是全知全能的 AI：

• 你需要给出明确具体的指令（Prompt 工程）
• 你需要检查它的产出（代码审查）
• 你需要告诉它公司规范（.cursorrules）
• 它速度快、不抱怨，但需要方向指引

这个心智模型帮你建立正确的使用预期：

你不会让实习生直接写核心支付逻辑，不给任何上下文
你不会让实习生改数据库 Schema 不审查
你不会让实习生做架构决策

同样的原则适用于 Cursor。

9.6 调试效率

AI 辅助调试工作流：

1. 遇到 Bug
2. 复制错误信息 + 相关代码到 Chat
3. 让 AI 分析根因
4. 确认分析正确后，让 AI 生成修复代码
5. 审查修复后应用

好的调试 Prompt：

运行测试时出现以下错误： Error: Hydration failed because the initial UI does not match what was rendered on the server. 相关文件：@/app/page.tsx 和 @/components/ClientCounter.tsx 请分析可能的原因，并给出修复方案。

9.7 测试生成

Cursor 在测试生成方面效率极高：

1. 打开目标文件
2. Ctrl+K 选中函数
3. 输入："/test 为这个函数生成单元测试，使用 Vitest，覆盖正常路径、边界条件和错误路径"
4. 审查并调整生成的测试

10 · 总结与下一步

10.1 核心原则回顾

Prompt 要具体 → 上下文要精准 → 模型要选对 → 代码要审查 → 规则要统一

10.2 九条黄金法则

10.3 持续改进

最佳实践不是一成不变的。Cursor 在快速演进，以下习惯能帮你保持领先：

• 每月回顾一次 .cursorrules
• 跟踪 Cursor Changelog
• 团队内部分享 Prompt 技巧
• 建立个人 Prompt 收藏库

10.4 实践清单

开始使用 Cursor 时，逐一核对：

• 创建 .cursorrules，包含技术栈和编码规范
• 配置 .claude/settings.json
• 建立 Notepad 项目上下文
• 掌握 Ctrl+K / Ctrl+L / Ctrl+I 快捷键
• 制定 AI 代码审查流程
• 团队统一 AI 协作契约
• 建立 Prompt 模板库

下一篇： 34 · 从 VSCode 迁移 — 完整迁移指南及插件替代方案

最后更新：2026-07-03 贡献者：ByteSurging Team