Cursor最佳实践

Cursor 是一款专为开发者设计的 AI 编程助手与集成开发环境（IDE），它通过智能补全、自动生成代码、文档理解、测试驱动开发等功能，帮助开发者提升开发效率、优化协作流程。Cursor 支持多种主流编程语言，并可通过自定义规则与插件，适配不同项目需求，是现代软件开发中 AI 辅助开发的代表性工具之一。

1. Cursor 最佳实践清单

1.1 制定 PRD 规划

利用 Cursor 的 AI 生成产品需求文档（PRD.md），为项目指明方向与结构（在团队协作中，可由产品经理在飞书等平台维护完整 PRD（面向人），同时在项目仓库中维护简化版 PRD.md（面向开发与 AI））。

• 在 PRD.md 中对目标、用户故事、非功能需求、范围、成功度量做最小完备定义。
• 将关键决策条目化，减少提示歧义，避免历史“飘移”。

1.2 在项目添加 Cursor 配置规则

• .cursorignore

  .cursorignore 用来告诉 Cursor 哪些文件或目录不要被索引或引用，从而提升性能并避免泄露敏感信息。

  # .cursorignore（精简示意）
  node_modules/
  dist/
  build/
  .tmp/
  .cache/
  coverage/
  
  .env.*
  *.pem
  *.key
  *.crt
  *.cert
  *.p12
  *.keystore

• rules

  规则文件用来指导 AI，每个规则文件使用 MDC（.mdc）格式编写，这种格式同时支持元数据和内容。在 Cursor 中打开 .mdc 文件后，可通过顶部的类型下拉菜单选择规则类型，该操作会自动更新 description、globs 和 alwaysApply 属性。

  规则类型	描述
  Always	始终包含在模型上下文中
  Auto Attached	当引用与某个 glob 模式匹配的文件时包含
  Agent Requested	提供给 AI，由其决定是否包含。必须提供描述
  Manual	只有在使用 @ruleName 明确提及时才会包含

  规则适用于 Chat 和 Inline Edit。已启用的规则会显示在 Agent 对话框的上下文管理栏（顶部）。

  • 可按模块拆分：
    • .cursor/rules/frontend.mdc
    • .cursor/rules/backend.mdc
    • .cursor/rules/tests.mdc

1.3 选择合适的 Agent 工作模式

Cursor Agent 提供三种工作模式，适用于不同开发场景：

• Plan 模式（规划模式）：在编写代码前先生成详细的实现方案。Agent 会研究你的代码库、提出澄清问题，并生成可审阅的方案，你可以在开始构建前进行编辑。适合复杂任务、架构设计、大规模重构等需要系统性规划的场景。

  • 工作流程：
    1. Agent 提出澄清性问题以了解需求
    2. 检索代码库并收集相关上下文
    3. 制定完整实现计划（以虚拟文件形式呈现）
    4. 你可审阅、编辑计划
    5. 点击"构建该计划"开始实施
  • 计划保存：可保存到 .cursor/plans/ 目录，便于团队共享和文档化

• Agent 模式：直接自动执行任务（如批量重构、自动测试、快速实现），适合明确目标和批量操作场景。

• Ask 模式：以对话为主，适合需求澄清、方案讨论、探索式协作。

使用建议：

• 复杂任务/架构设计 → 优先用 Plan 模式，先规划后执行
• 明确的开发/测试/重构 → 用 Agent 模式，快速迭代
• 需求沟通/方案探讨 → 用 Ask 模式，深度对话

1.4 选择合适的 AI 模型

主流模型区别与推荐场景：

模型	特点/优势	推荐场景
GPT-4.1	代码/推理能力强，兼容性好	日常开发、测试、复杂推理
GPT-5	最新一代，推理与生成更强	架构设计、长文本、复杂任务
Claude-4.5	代码与推理全面升级	高质量代码生成、架构设计
Claude-4 Sonnet	语境理解好，文本推理强	需求澄清、文档生成
Claude-4 Opus	超长上下文、推理极强	大型项目、长链路推理
Claude-3.5/3.7	性能均衡，成本低	日常对话、轻量任务
Gemini 2.5 Pro	多模态支持，速度快	图文混合、快速实验
Grok 系列	速度快，适合实时场景	快速问答、低延迟需求
o3/o4-mini	成本极低，适合批量任务	批量生成、低优先级任务
Deepseek	中文支持好，代码能力强	中文开发、代码生成
Kimi-K2	中文长文本处理能力突出	中文文档、长文本摘要
GPT-5 Codex	代码理解/重构/迁移更强	大规模重构、复杂代码生成
GPT-5 Mini	低成本、延迟低	轻量开发、原型验证
GPT-5 Nano	体积小、响应快	快速问答、简单脚本、批量任务
Gemini 2.5 Flash	速度快、成本低，多模态	高并发、图文混合、快速试验
Grok Code	面向代码优化、速度快	代码阅读、修复、测试生成
Haiku 4.5	轻量稳定、成本友好	文案润色、摘要、快速问答
DeepSeek R1	强推理、数学表现佳	复杂推理、数学/算法题
DeepSeek V3.1	代码与中文双优、性价比高	中文开发、代码补全/生成
o3 Pro	更强思考链路与工具使用	深度推理、系统设计、复杂规划

• 实践建议：
  • 日常开发/测试：优先 GPT-4.1、Claude-4 Sonnet
  • 架构设计/复杂推理：可选 GPT-5、Claude-4 Opus
  • 快速实验/低成本：Gemini、Grok、o3/o4-mini
  • 多模态（图文/代码）：Gemini 2.5 Pro
• 可根据任务难度、上下文长度、成本灵活切换，优先保证结果质量和语境理解。

1.5 使用 @ 标签提供上下文

通过合理使用 @File、@Web、@Code、@Terminal 等标签，将关键上下文信息注入 prompt，可显著提升 AI 的理解度与结果质量。例如：

• @File：指定具体文件内容或路径，适合代码变更、定位 bug、结构分析。
• @Code：直接引用代码片段，适合讨论实现细节、重构建议、单元测试。
• @Web：补充外部网页或文档链接，适合查阅 API、第三方库、设计规范。
• @Terminal：引入终端命令或运行结果，适合调试、构建、测试反馈。

建议：每次协作时，优先补充与目标相关的上下文标签，减少歧义，提升沟通效率。 此外，你也可以直接选中代码片段添加到对话，或将代码/文本复制粘贴到对话框，AI 同样能自动识别并应用这些上下文信息，无需额外标签。

1.6 TDD 驱动迭代（先测后码）

• 先为关键用户流写测试（最开始失败），再最小实现直至通过。
• 单元测试覆盖组件输入/输出与边界；集成测试覆盖核心操作流（新增 → 勾选 → 删除 → 筛选/排序等）。
• 测试环境要保证用例隔离（如清理 localStorage、组件卸载等）。

1.7 自动运行

• Auto-Run Mode 允许 Agent 在安全边界内自动执行任务，如跑测试、类型检查、Lint。
• 推荐默认 Ask Every Time；必要时仅对白名单命令自动运行：npm test（或 npm run test:watch）、npm run build（可选；如已配置 lint/typecheck 再加入）。
• 每次只围绕一个清晰目标：先加测试 → 跑测（红）→ 最小实现 → 跑测（绿）。
• 大改前先建分支并提交快照；限定可改目录与行数，超限需人工确认。

1.8 基于测试驱动策略构建迭代反馈循环

在较大项目中，建议每完成一个阶段性功能后，设置 1–2 个关键集成测试作为 checkpoint。通过自动化测试及时发现并修复编码错误，既能保障项目安全边界，又能提升开发效率。AI 可根据测试结果自动定位并修复问题，实现高效迭代。

2. TodoList 实践案例

本章节基于 TodoList 项目，详细记录每个开发阶段的具体操作步骤、命令和提示词。

2.1 第一步：制定 PRD 规划

目标：明确产品需求和技术边界

具体操作：

创建 PRD.md 文件，定义：

• 用户故事（Given/When/Then 格式）
• 验收标准（如：输入验证、状态切换、数据持久化）
• 技术栈选择（React + TypeScript + Vite + Vitest）
• MVP 范围（核心组件：TodoItem、TodoEditor）

示例提示词：

帮我创建一个 TodoList 应用的 PRD.md，包含：
- 6个核心用户故事（增删改查、筛选、搜索）
- 每个故事的 Given/When/Then 验收标准
- 明确 MVP 边界，排除用户系统和多端同步

2.2 第二步：生成项目骨架

目标：搭建可运行的开发环境

示例提示词：

帮我配基础开发环境：
1. 使用 Vite 初始化 React+TS 项目
2. 创建 vitest.config.ts，使用 jsdom 环境
3. 创建 vitest.setup.ts，导入 @testing-library/jest-dom
4. 确保组件测试可以在浏览器外运行

2.3 第三步：添加 Cursor 配置

目标：建立 AI 协作的行为约束

具体操作：

配置 .cursorignore 文件

示例提示词：

请根据官方与社区常见规范，生成一份 .cursorignore 文件。
要求：
- 排除构建产物、依赖目录（如 node_modules、dist、build 等）
- 排除临时文件、日志、系统文件（如 *.log、*.tmp、.DS_Store）
- 排除测试覆盖率报告（如 coverage、.nyc_output）
- 排除敏感文件（如 .env*、*.pem、*.key）
- 包含常见前端/后端项目的约定忽略项

创建通用开发规则

示例提示词：

创建 .cursor/rules/index.mdc 通用开发规则：

---
alwaysApply: true
---

# 技术栈约束

- TypeScript 严格模式，React 18 + Vite
- 函数式组件 + Hooks，避免类组件
- 测试使用 Vitest + @testing-library/react
- 文件命名：kebab-case，组件用 PascalCase.tsx

确保 AI 在所有开发中遵循这些约束

创建测试专用规则

示例提示词：

创建 .cursor/rules/testing.mdc 测试规则：
---
globs: **/*.test.tsx, **/__tests__/**
---

# 测试约定

- 优先 TDD：先写失败测试，再实现功能
- 覆盖：正常路径、边界条件、异常输入
- 循环：执行 npm test，失败时自动修复

自动应用到测试相关文件

2.4 第四步：启用自动化工作流

目标：配置 Cursor Agent 自动运行测试和构建

具体操作：

配置路径：Cursor → Settings → Agents → Auto-Run Mode(版本 2.0.43，不同版本可能会有差异)

在 Cursor 设置中配置 Auto-Run Mode 为 "Use Allowlist"，并设置命令白名单：

• 允许：npm test、npm run build、npm run dev、npm run lint
• 禁止：rm、git push、npm publish 等危险命令

安全实践：

• 在开启自动运行前先提交代码（git commit）
• 限制 AI 权限在安全命令范围内
• 不授予生产环境凭证的写权限

2.5 第五步：TDD 红-绿-重构循环开发

目标：在自动化环境下遵循 TDD 最佳实践，逐个组件进行红-绿-重构循环

TDD 循环说明：

• 🔴 红：写一个失败的测试
• 🟢 绿：写最少代码让测试通过
• 🔵 重构：在保持测试通过的前提下优化代码（可选）

重构完成后的下一步：

1. 验证测试通过：确保所有现有测试仍然通过，重构没有破坏功能
2. 评估覆盖度：检查是否需要补充边界条件或异常情况的测试
3. 开始新循环：
   • 如果当前组件功能完整，进入下一个组件的红-绿-重构循环
   • 如果需要新功能，为新功能编写失败测试，开始新的 TDD 循环
4. 集成验证：定期运行完整测试套件，确保各组件协同工作正常

TodoItem 组件 TDD 循环

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/components/__tests__/todo-item.test.tsx：
  
  测试用例：
  1. 渲染文本与初始完成状态
  2. 勾选触发 onToggle(id, next)
  3. 点击删除触发 onDelete(id)
  
  Todo 模型：{ id: string, text: string, completed: boolean, createdAt: string }
  使用 Vitest + Testing Library，包含 vi.fn() mock

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/components/todo-item.tsx，仅满足测试通过：
  @Files src/components/__tests__/todo-item.test.tsx
  
  最小实现要求：
  1. 接收 todo、onToggle、onDelete props
  2. 复选框绑定 completed 状态
  3. 删除按钮触发 onDelete
  
  AI 将自动运行 npm test 确保测试通过（绿）

• 重构阶段 - 优化代码

  示例提示词：

  重构 TodoItem 组件，保持测试通过：
  1. 优化组件结构和可读性
  2. 改进无障碍访问性
  3. 优化样式和用户体验
  
  AI 将在每次修改后自动运行 npm test 确保测试仍然通过

TodoEditor 组件 TDD 循环

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/components/__tests__/todo-editor.test.tsx：
  1. 受控输入：输入文本后 value 更新
  2. 空值禁用：空字符串时提交按钮禁用
  3. 提交清空：提交后触发 onAdd({text}) 并清空输入框
  4. 键盘支持：回车键提交
  

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/components/todo-editor.tsx 最小功能：
  @Files src/components/__tests__/todo-editor.test.tsx
  
  基本功能：
  1. 受控文本输入框
  2. 空值时禁用提交按钮
  3. 提交时调用 onAdd({text}) 并清空
  4. 支持回车键提交
  
  运行 npm test 确保测试通过（绿）

• 重构阶段 - 优化代码

  示例提示词：

  重构 TodoEditor 组件：
  1. 优化表单验证逻辑
  2. 添加适当的 loading 状态
  
  保持测试通过的前提下进行优化

App 组件 TDD 循环

• 红阶段 - 写失败测试

  示例提示词：

  创建 src/app/__tests__/app.integration.test 集成测试：
  1. 页面加载：从 localStorage 读取数据
  2. 完整流程：添加 → 切换完成 → 筛选 → 删除
  3. 数据持久化：操作后 localStorage 更新
  
  使用 jsdom 模拟 localStorage

• 绿阶段 - 最小实现

  示例提示词：

  实现 src/app/app.tsx 基本功能：
  @Files src/app/__tests__/app.test.tsx
  
  核心功能：
  1. localStorage 数据持久化（key: 'todo-app:v1'）
  2. 基本状态管理：todos、filter
  3. 事件处理：onAdd、onToggle、onDelete
  4. 简单筛选逻辑：all/active/completed
  
  运行 npm test 确保测试通过（绿）

• 重构阶段 - 优化架构

  示例提示词：

  重构 App 组件架构：
  1. 提取状态管理逻辑（useReducer 或自定义 hooks）
  2. 改进错误处理和边界情况
  3. 添加按创建时间排序等高级功能
  
  每次重构后自动确保所有测试通过

2.6 第六步：配置 CI/CD 流水线

目标：建立自动化测试和部署流程

具体操作：

创建 GitHub Actions

示例提示词：

生成 .github/workflows/ci.yml 工作流：
1. 触发条件：push 和 PR 到 master 分支
2. 环境：Node.js 20
3. 步骤：checkout → install → build → test → coverage
4. 失败时阻止合并

配置部署流程

示例提示词：

创建 Vercel 部署配置：
1. 生成 vercel.json 配置文件
2. 设置构建命令和输出目录
3. 配置环境变量和重定向规则

2.7 第七步：完善文档和验收

目标：生成完整的项目文档和验收测试

具体操作：

生成项目文档

示例提示词：

更新 README.md 包含：
1. 项目介绍和功能特性
2. 技术栈和架构说明
3. 本地开发指南（安装、运行、测试）
4. 部署链接和演示
5. 贡献指南和许可证

创建验收测试清单

示例提示词：

创建 ACCEPTANCE.md 验收清单：
1. 功能测试：所有用户故事验证通过
2. 技术测试：测试覆盖率 > 80%，构建成功
3. 用户体验：响应式设计，无障碍访问
4. 性能测试：首屏加载 < 2s

总结

Cursor 最佳实践的核心在于建立系统化的 AI 协作流程，通过以下关键要素实现高效开发：

核心原则

1. TDD 驱动迭代：以测试为先导，相比于人工开发中“先实现再测试”的习惯，TDD 在 AI 辅助下更具价值， 它能作为清晰的反馈循环与安全护栏，帮助 AI 保持正确的开发方向。
2. 结构化配置：通过 PRD 规划、规则文件、上下文标签等，为 AI 提供明确的行为约束和项目背景
3. 自动化反馈：利用 Auto-Run 模式建立快速验证机制，实现"红-绿-重构"的高效循环

适用范围

这套最佳实践不仅适用于 Cursor，也可推广到其他 AI 编程助手（如 Trae、GitHub Copilot 等），只需根据具体工具的配置方式进行调整。关键在于理解 AI 协作的本质：通过结构化输入和反馈循环，让 AI 成为更可靠的编程伙伴。

参考资料

• Cursor 官方文档
• Mastering Cursor IDE: 10 Best Practices Building a Daily Task Manager App (Medium)
• Cursor Best Practices (GitHub)
• Cursor IDE 规则与 AI 协作（Kirill Markin 博客）
• Cursor Prompt Engineering 最佳实践（官方论坛）
• Cursor Tips（Builder.io 博客）
• 中大型项目最佳实践（官方论坛）
• Mastering Cursor IDE: Thinking Models, Cursor Rules and Effective Usage (Medium)
• Cursor IDE Setup and Workflow in Larger Projects（Reddit）
• Cursor Tips（dev.to）