【AI】cursor使用场景示例

基于 Cursor 官方文档及高赞社区实践按 8 个高频开发场景 给出可直接复制粘贴的 Prompt 模板。每个模板遵循官方推荐的 6 段式结构 （Goal → Context → Constraints → Examples → Output → Verify），并内嵌 @ 上下文引用语法。

---

一、新功能开发（多文件）

适用：涉及 API、UI、状态管理等多处改动的需求。

Goal: 为 /invoices API 添加分页支持，保留现有筛选和排序能力。

Context: 
- 后端逻辑在 @src/api/invoices.ts，当前无分页参数
- 路由层在 @src/routes.ts
- 现有筛选逻辑依赖 query 参数：status、dateRange、customerId

Constraints:
- 使用项目现有 Zod 校验规则，不引入新依赖
- 不改数据库 Schema，分页在应用层实现
- 保持现有 API 响应结构，仅新增 meta 字段

Examples:
- 请求 GET /invoices?page=2&limit=20&status=paid 
- 响应 { data: [...], meta: { page: 2, limit: 20, total: 147 } }

Output:
1. 先输出 Plan（步骤清单 + 涉及文件 + 风险点），等我确认
2. 确认后按文件输出 unified diff
3. 每个改动文件附 1-2 行改动说明

Verify:
- 运行 pnpm test && pnpm lint，确保通过
- 列出 5 个 edge case（如 page=0、limit>100、total=0）并确认覆盖

核心要点 ：非 trivial 改动强制走 Plan Mode（先计划、后执行），避免 AI 直接改出一堆半对代码 。

---

二、Bug 调试

适用：线上问题复现、根因定位、最小修复。

Goal: 定位并修复认证超时问题，确保 token 刷新机制正常工作。

Context:
- 认证中间件在 @src/middleware/auth.ts
- token 生成逻辑在 @src/services/token.ts
- 当前现象：用户登录 30 分钟后操作报 401，刷新页面后恢复

Constraints:
- 不改动登录流程和前端调用方式
- 保持现有 token 存储格式（Redis + JWT）
- 修复必须附带回归测试

Output:
1. 先基于复现步骤分析完整调用链（login → token gen → session → validation → timeout）
2. 提出 2 个最可能的根因假设
3. 实现最小修复，输出 diff
4. 附测试用例证明修复有效

Verify:
- 列出你检查过的 3 个集成点（frontend→backend, backend→Redis, token→session）
- 确认无 secrets 泄露、无性能退化（如 N+1 查询）

核心要点 ：要求 AI 先复现流程、再提假设、最后修，禁止直接跳去改 timeout 数值 。

---

三、安全重构（不改行为）

适用：降复杂度、优化性能、迁移写法，但功能必须 100% 等价。

Goal: 重构 @src/utils/legacyParser.ts 以降低圈复杂度，提升可读性。

Context:
- 当前文件 400+ 行，嵌套 5 层 if-else，无单元测试
- 被 3 个模块引用：@src/api/upload.ts、@src/jobs/scheduler.ts、@src/cli/import.ts

Constraints:
- 绝对禁止行为变更，输入输出必须逐字等价
- 不新增外部依赖
- 保持现有函数签名（除非签名本身也是重构目标，需额外说明）

Output:
1. 输出重构前后对比说明（before/after 逻辑映射）
2. 按文件输出 unified diff
3. 新增/调整测试以证明等价性

Verify:
- 运行现有测试套件，确认全部通过
- 若原文件无测试，先生成测试覆盖 happy path + 3 个 edge cases，再重构
- 检查 3 个引用点是否受影响

核心要点 ：用 "Refactor" 明确触发全量重写，用 "Change" 容易得到补丁式修改 。

---

四、生成测试（TDD 风格）

适用：补测试债、新功能先行写测试。

Goal: 为 @src/services/payment.ts 中的 processRefund 函数生成完整测试。

Context:
- 项目使用 Vitest，现有测试在 @tests/services/payment.test.ts
- processRefund 依赖外部 API（Stripe）和数据库事务

Constraints:
- 使用现有 Vitest + MSW 模拟 HTTP，不引入新 mock 库
- 数据库操作必须 mock，禁止真实调用
- 覆盖率目标 80%+

Examples:
- Happy path: orderId 有效、金额匹配、Stripe 返回 success → 更新订单状态为 refunded
- Edge case: orderId 不存在 → 抛 NotFoundError
- Edge case: Stripe 网络超时 → 抛 PaymentGatewayError，订单状态不变

Output:
1. 先输出测试大纲（Test Outline）：场景列表 + 输入/预期输出
2. 等我确认后，输出完整测试代码 diff
3. 附运行命令和覆盖率报告片段

Verify:
- 运行 pnpm test tests/services/payment.test.ts，粘贴结果
- 确认无真实网络请求、无硬编码 secrets

核心要点 ：测试生成先出 Outline 再出代码，避免 AI 遗漏边界 。

---

五、代码审查（Code Review）

适用：让 AI 扮演 reviewer，发现性能、安全、规范问题。

Goal: Review 选中代码，聚焦性能、安全、代码标准、潜在 bug。

Context:
- 代码来自 @src/components/DataGrid.tsx（选中部分）
- 该组件渲染 10k 行表格数据，支持虚拟滚动

Constraints:
- 按严重度分级：Critical / Warning / Suggestion
- 每个问题必须给出具体修复代码片段
- 不重构整体架构，仅指出当前代码问题

Output:
1. 问题清单（行号 + 严重度 + 说明 + 修复建议）
2. 若发现性能问题，给出 benchmark 或复杂度分析
3. 若发现安全问题，说明攻击向量

Verify:
- 确认所列问题在 @src/components/DataGrid.tsx 中确实存在
- 排除误报（如误把合法的正则当 ReDoS）

核心要点 ：可保存为 Custom Command /review，一键执行，效率提升 80% 。

---

六、生成文档 / API 文档

适用：补 JSDoc、写 README、生成接口文档。

Goal: 为 @src/api/invoices.ts 生成 API 文档。

Context:
- 该文件包含 RESTful endpoints：GET /invoices, POST /invoices, GET /invoices/:id
- 使用 Express + Zod，错误处理统一返回 { error: string, code: string }

Constraints:
- 文档格式：Markdown
- 包含：endpoint、method、请求参数、响应示例、错误码
- 不暴露内部实现细节（如数据库表结构）

Output:
1. 生成可直接放入 docs/api/invoices.md 的内容
2. 请求/响应示例使用真实数据格式（如 ISO 日期、UUID）
3. 错误码表格（HTTP Status + 业务 code + 说明）

Verify:
- 对照 @src/api/invoices.ts 源码，确认参数和响应结构一致
- 检查是否有已废弃 endpoint 未标注

---

七、快速小修（单行/单文件）

适用：改配置、加日志、修 typo、简单格式化。

Goal: 在 @src/config/database.ts 的 connect() 函数内添加连接超时日志。

Context:
- 当前 connect() 失败时静默重试，无日志
- 项目使用 pino 做日志，已有实例在 @src/lib/logger.ts

Constraints:
- 仅添加日志，不改连接逻辑和重试策略
- 日志级别用 warn，包含重试次数和错误消息

Output:
1. 直接输出 unified diff（无需 Plan）
2. 附 1 行改动说明

Verify:
- 确认无语法错误，不引入新依赖

核心要点：简单任务跳过 Plan Mode，直接 diff；复杂任务必须拆分多轮 。

---

八、复杂多 Agent/多步骤任务（研究型）

适用：需要 AI 先理解系统、再决策、再执行的深度任务。

Goal: 优化 EtherCAT 主站时延，目标 cycle time < 1ms。

Context:
- 主站代码在 @src/ethercat/master.c
- 当前使用 SOEM 库，平台为 x86_64 Linux RT-PREEMPT
- 已存在配置 @config/ethercat.yaml

Constraints:
- 不改 EtherCAT 从站固件
- 保持现有 PDO 映射
- 优化必须可量化（附 benchmark 方法）

Output:
1. Phase 1 - Research：分析当前代码路径、锁竞争、中断延迟，输出诊断报告
2. Phase 2 - Plan：提出 2-3 个优化方案（优缺点 + 风险），等我确认
3. Phase 3 - Execute：实现选定方案，输出 diff + benchmark 结果
4. Phase 4 - Verify：运行测试，确认 cycle time 达标，更新 @docs/performance.md

Verify:
- 每个 Phase 结束前必须自检：是否有 blocker？是否需要用户澄清？
- 完成标准：不只是"编译通过"，而是"端到端验证通过" 

核心要点 ：强制 Chain of Prompts（计划 → 代码 → 测试 → 文档），每轮输出可控 。

---

附：万能黄金公式（日常随手用）

如果记不住 6 段式，用社区总结的 一句话公式 ：

具体任务 + 技术要求 + 上下文引用(@) + 预期结果

示例：

给 @pages/Dashboard.tsx 添加数据导出功能，支持 CSV 和 Excel。
UI 风格参考 @components/ExportButton.tsx，导出逻辑使用现有 xlsx 库。
需要包含当前筛选条件下的全部数据。

---

附：项目级底座配置（一次配置，长期受益）

把以下规则写入项目根目录 .cursorrules，Cursor 会自动在所有对话中遵守 ：

# 代码规范
- 新模块放在 src/features/ 下，按功能域组织
- 错误处理统一使用现有 Result<T, E> 模式，不抛裸异常
- 命名：函数 camelCase，类型 PascalCase，常量 SCREAMING_SNAKE_CASE

# 安全护栏
- 禁止修改公共函数签名，除非附带迁移方案
- 禁止新增依赖，除非用户明确要求
- 不得记录 secrets，token 必须哈希存储

# 完成前必须执行
- 运行 pnpm lint && pnpm test 通过后再标记完成
- 修改后更新相关文档，标注日期，引用代码行号
- 复杂任务必须先输出 Plan，等我确认后再执行