Cursor AI 编程实战（篇一）：Prompt 与案例总结

Cursor AI 编程实战（篇一）：Prompt 与案例总结

系列 ：共三篇。本篇讲「为什么 Prompt 重要」+ 可直接复制的技术方案 / 代码生成 / 数据割接三类大模板，以及 PDF 对接案例与迭代建议。
下一篇 ：篇二：Rules、速查片段与 Adapter/App 全文
第三篇 ：篇三：Domain、Infrastructure 与策略模式全文
合并完整版 （单文件，含全部附录）：Cursor-AI编程最佳实践-CSDN发表版.md

---

系列说明：本文为《Cursor AI 编程实战》连载之一，。三篇可独立阅读，也可按篇一 → 篇二 → 篇三顺序配合使用。

本篇正文

摘要（篇一） ：聚焦 Prompt 三层结构、三份可复制的长提示词模板，以及第三方 PDF 对接案例与持续迭代建议。Rules 与分层 .mdc 全文见篇二、篇三。
关键词 ：Cursor、Prompt Engineering、AI 编程
声明：脱敏整理，仅供技术交流。

---

一、问题从哪来：理想与现实的落差

问题类型	具体表现	影响
生成可信度不足	虚构接口、逻辑错误	反复调试，陷入低效对话
规范适配缺失	命名、分层、注释与项目不一致	大量手工返工
上下文理解浅	抓不住关键业务链路	难做深度重构
输出不稳定	同一需求多次结果差异大	难以标准化协作

这些往往不全是「模型不行」，而是输入质量 与约束体系没跟上。可记一个简单公式：

Cursor 输出质量 ≈ 精确、可执行的 Prompt + 有效、可继承的 Rule 约束

系列后两篇专讲 Rules 与 分层 .mdc 全文（见篇二、篇三链接于篇首）。

---

二、Prompt：先结构，再聊天

2.1 三层架构：目标 → 背景 → 要求

1. 目标：说清楚要设计、写代码、分析还是迁移；交付物是什么。
2. 背景：业务约束、技术栈、文档路径、相关模块。
3. 要求：步骤拆解、禁止项、输出格式、质量检查点。

2.2 延伸学习

系统学习可参考：Prompting Guide

---

三、可直接套用的 Prompt 模板（完整版）

3.1 技术方案生成

# 技术方案生成 Cursor 提示词

## 目标
作为资深开发工程师，基于现有项目代码和需求文档，生成完整详细的技术方案文档。专注于方案设计和技术架构，现阶段不涉及代码实现。

## 背景
- 项目已有完整的代码库，包含现有的技术架构和业务逻辑
- 需求文档已明确定义了功能改动和业务需求，文档路径为：/docs/prd/*_prd.md
- 需要在现有架构基础上设计新功能的技术实现方案
- 技术方案将作为后续开发阶段的指导文档

## 要求

### 任务步骤

#### 1. 需求分析与理解阶段
- **深度需求解读**
  - 逐条分析需求文档中的功能点、业务规则和约束条件
  - 识别核心功能、辅助功能和可选功能的优先级
  - 提取非功能性需求（性能、安全、可用性等）
  - 标记需求中的模糊点、矛盾点或缺失信息，并提出澄清建议

- **影响范围评估**
  - 分析新需求对现有系统的影响范围
  - 识别需要修改的模块、接口和数据结构
  - 评估向前兼容性和向后兼容性要求

#### 2. 现有架构分析阶段
- **代码架构梳理**
  - 分析项目的分层架构（Controller、Service、DAO 等）
  - 理解技术栈选型（框架、中间件、数据库等）
  - 梳理核心业务流程和数据流向
  - 识别设计模式和架构原则的应用

- **可复用资源盘点**
  - 列出可复用的工具类、公共组件和基础服务
  - 分析现有的异常处理机制和日志体系
  - 梳理可扩展的接口和抽象类
  - 识别现有的配置管理和部署机制

#### 3. 技术方案设计阶段
- **整体架构设计**
  - 设计新功能在现有架构中的位置和交互关系
  - 定义模块边界和职责划分
  - 设计数据流和控制流
  - 制定接口规范和数据协议

- **详细设计规划**
  - 数据库设计：表结构、索引、约束关系
  - 接口设计：API 规范、参数定义、返回格式
  - 业务逻辑设计：核心算法、业务规则、状态转换
  - 异常处理设计：异常分类、处理策略、回滚机制

#### 4. 文档输出阶段
- **技术方案文档编写**
  - 生成结构化的技术方案文档
  - 包含架构图、时序图、数据流图等可视化内容
  - 提供详细的实现步骤和开发指导

### 限制条件
- **输出限制**
  - 只输出技术方案文档，不生成任何代码实现
  - 不修改现有项目文件，只创建新的方案文档
  - 文档必须放置在项目的 docs 目录下

- **方案质量要求**
  - 方案必须基于现有代码架构，保持技术栈一致性
  - 设计方案需考虑可扩展性、可维护性和性能要求
  - 必须提供清晰的实现路径和里程碑规划
  - 识别和标记技术风险点及应对策略

- **文档规范要求**
  - 使用 Markdown 格式编写，结构清晰易读
  - 包含完整的目录结构和章节导航
  - 提供必要的架构图和流程图
  - 包含变更影响分析和回滚方案

### 输出格式要求

**技术方案文档结构**：
```markdown
# [功能名称]技术方案

## 1. 需求概述
## 2. 现状分析
## 3. 术语表
## 4. 模块依赖
## 5. 用例图
## 6. 领域设计
### 6.1 领域对象
### 6.2 ER关系
### 6.3 对象设计
## 7. 状态机（单据）
## 8. 关键业务设计
## 9. 接口设计

文件命名规范：

• 文件名：[功能模块]_技术方案_v[版本号].md
• 存放路径：docs/technical-solutions/

质量检查点

• 方案是否完整覆盖需求文档中的所有功能点

• 设计是否与现有架构保持一致性和兼容性

• 是否识别了所有潜在的技术风险和依赖关系

• 实现计划是否具有可操作性和合理的时间估算

• 文档是否具备足够的细节指导后续开发工作

  3.2 代码生成

  # 代码生成 Cursor 提示词
  
  ## 目标
  作为资深开发工程师，基于已确定的技术方案和需求文档，生成符合项目规范的高质量代码实现。确保代码与现有架构无缝集成，遵循项目开发规范。
  
  ## 背景
  - 需求文档已明确定义业务需求和功能规格，文档路径为：/docs/prd/*_prd.md
  - 技术方案文档已提供详细的架构设计和实现指导，文档路径为：docs/technical-solutions/*_tech.md
  - 项目代码库具有成熟的架构体系和开发规范
  - 需要在现有代码基础上实现新功能，保持代码风格和架构一致性
  - 后端开发规范文档定义了代码质量标准和编程约束
  
  ## 要求
  
  ### 任务步骤
  
  #### 1. 文档一致性验证阶段
  - **需求与方案匹配度检查**
    - 逐项对比需求文档与技术方案的功能点覆盖情况
    - 验证输入参数、输出结果、数据格式的一致性
    - 检查异常场景、边界条件的处理方案匹配度
    - 确认性能指标、安全要求等非功能性需求的技术实现
  
  - **矛盾点识别与处理**
    - 标记需求文档与技术方案中的不一致之处
    - 对于发现的矛盾点，提供具体的差异说明和建议解决方案
    - 在代码实现前必须解决所有标记的矛盾点
  
  #### 2. 现有架构深度分析阶段
  - **代码库结构理解**
    - 分析项目的分层架构和模块划分
    - 理解依赖注入、配置管理、数据访问等核心机制
    - 识别代码生成器、AOP 切面、拦截器等基础设施
    - 梳理现有的测试框架和测试策略
  
  - **可复用资源盘点**
    - 扫描并列出可复用的工具类、常量定义、枚举类型
    - 分析现有的异常处理体系和自定义异常类
    - 识别可扩展的接口、抽象类和基础组件
    - 梳理现有的公共方法、验证逻辑和业务规则
  
  - **集成点分析**
    - 确定新功能在现有架构中的准确位置
    - 分析与现有模块的交互接口和数据传递方式
    - 识别需要修改的配置文件和依赖关系
    - 评估对现有功能的潜在影响
  
  #### 3. 代码实现阶段
  - **编码准备工作**
    - 创建必要的目录结构和包路径
    - 定义新增的常量、枚举和配置项
    - 设计数据传输对象（DTO）和值对象（VO）
    - 准备单元测试和集成测试的基础框架
  
  - **分层代码实现**
    - **数据访问层（DAO/Repository）**：实现数据库操作和数据映射
    - **业务逻辑层（Service）**：实现核心业务逻辑和事务管理
    - **控制层（Adapter）**：实现接口路由和参数验证
    - **公共组件**：实现工具类、异常处理和配置管理
  
  - **代码质量保证**
    - 添加完整的 Java Doc 注释和关键代码注释
    - 实现适当的日志记录和监控埋点
    - 添加参数验证和异常处理逻辑
    - 编写对应的单元测试和集成测试
  
  ### 限制条件
  
  #### 代码风格一致性要求
  - **严格遵循项目现有的代码风格**
    - 变量命名、方法命名、类命名必须与项目规范一致
    - 代码缩进、换行、空格使用必须保持统一
    - 注释风格和文档格式必须符合项目标准
    - 包结构和文件组织方式必须遵循现有模式
  
  #### 代码复用最大化原则
  - **优先复用现有代码**
    - 在现有方法基础上进行扩展而非重写
    - 通过方法重载满足新需求，避免重复实现
    - 复用现有的工具类、常量定义和公共组件
    - 扩展现有接口而非创建新的相似接口
  
  - **最小化代码变更**
    - 新增功能优先通过配置和扩展实现
    - 避免修改现有核心业务逻辑
    - 通过继承和组合减少侵入性修改
    - 保持现有 API 的向后兼容性
  
  #### 开发规范遵循要求
  - **严格按照团队《工程结构规范》执行**
    - 遵循规范中定义的架构原则和设计模式
    - 执行规范中的代码质量检查标准
    - 实施规范中的安全编码要求
    - 符合规范中的性能优化指导
  
  ### 输出要求
  
  #### 必须包含的代码内容
  - **完整的业务实现代码**
    - 所有层次的完整实现，不允许有空方法或 TODO 标记
    - 完整的异常处理和参数验证逻辑
    - 必要的事务管理和数据一致性保证
    - 完整的日志记录和错误跟踪
  
  - **配套测试代码**
    - 单元测试覆盖所有核心业务方法
    - 集成测试验证完整业务流程
    - 测试用例覆盖正常场景和异常场景
    - Mock 对象和测试数据的合理设计
  
  #### 代码质量检查清单
  - 代码是否完全符合技术方案的设计要求
  - 是否最大化复用了现有代码和组件
  - 是否遵循了项目的代码风格和命名规范
  - 是否添加了完整的注释和文档
  - 是否包含了充分的异常处理和验证逻辑
  - 是否编写了对应的单元测试和集成测试
  
  ### 交付说明
  - 所有新增代码必须放置在项目代码库的正确位置
  - 修改现有文件时必须保持原有功能的完整性
  - 提供代码变更说明和部署注意事项
  - 确保代码可以通过现有的构建和测试流程

3.3 数据割接（CSV → MySQL）

## 目标
你是一个资深的数据库工程师，请基于提供的 CSV 数据文件和字段映射关系，生成完整的 MySQL INSERT 脚本，用于数据库数据割接迁移。

## 背景
- 需要将历史数据从 CSV 文件迁移到新的 MySQL 数据库表中
- CSV 文件包含原始业务数据，字段名称可能与目标数据库表字段不一致
- 需要根据字段映射关系进行数据转换和格式化
- 生成的 SQL 脚本需要能够直接在 MySQL 环境中执行

## 要求

### 任务步骤
1. **解析 CSV 文件结构**
   - 读取并分析 CSV 文件的表头和数据类型
   - 识别数据中的空值、特殊字符等需要处理的情况
   - 统计数据行数和基本数据质量情况

2. **应用字段映射关系**
   - 根据提供的字段对应关系，将 CSV 字段名映射到数据库字段名
   - 处理字段类型转换（如日期格式、数值格式等）
   - 标识缺失的必填字段并提供默认值策略

3. **数据清洗和转换**
   - 处理 NULL 值：空字符串转为 NULL，特殊标记（如 "N/A"、"-"）转为 NULL
   - 转义特殊字符：单引号、双引号、反斜杠等 SQL 特殊字符
   - 日期时间格式统一转换为 MySQL 标准格式（YYYY-MM-DD HH:MM:SS）
   - 数值类型验证和格式化

4. **生成 INSERT 脚本**
   - 生成批量 INSERT 语句，每批处理 1000 条记录
   - 添加适当的事务控制（BEGIN/COMMIT）
   - 包含错误处理和回滚机制
   - 添加执行进度注释

### 限制条件
- 生成的 SQL 必须符合 MySQL 语法规范
- INSERT 语句必须包含完整的字段列表，不允许省略字段名
- 所有字符串值必须正确转义，防止 SQL 注入
- 数值类型不能包含引号，字符串类型必须包含引号
- 日期时间必须使用 MySQL 标准格式
- 生成的脚本文件大小控制在合理范围内（建议单个文件不超过 100MB）

### 输出格式要求
- 在脚本开头添加注释说明：数据来源、生成时间、记录总数
- 使用事务包装每批 INSERT 操作
- 在每 1000 条记录后添加 COMMIT 语句
- 在脚本末尾添加数据验证查询语句
- 提供执行前的备份建议注释

### 错误处理
- 对于数据类型不匹配的情况，提供转换建议或跳过策略
- 对于缺失必填字段的记录，生成警告信息
- 提供数据质量报告，包括转换成功率、异常记录数量等

### 示例输出格式
```sql
-- 数据割接脚本
-- 来源文件: [CSV文件名]
-- 生成时间: [时间戳]
-- 总记录数: [数量]
-- 目标表: [表名]

START TRANSACTION;

INSERT INTO target_table (field1, field2, field3) VALUES
('value1', 'value2', 'value3'),
('value1', 'value2', 'value3');
-- ... 每1000条记录一批

COMMIT;

---

---

## 六、案例复盘：第三方接口 PDF → 可引用文档 → 代码

某**连锁门店零售**项目中，需对接银联类 POS（聚合扫码、刷卡等）。可复用路径：

1. **PDF → Markdown**：因 IDE 不便直接吃 PDF，可借助外部工具，提示词示例：

```markdown
请将我上传的 PDF 文件准确地转换为结构清晰、格式规范的 Markdown（.md）文档。转换时请保留原文的标题层级、段落结构、列表、表格和代码块等格式。若 PDF 中包含图片，请在 Markdown 中用合适的占位符标注（如 ![图片描述](图片链接)），并简要说明图片内容。确保转换后的内容易于阅读、便于后续编辑与引用。

转换后务必人工核对：请求地址、必填参数、签名与安全字段。

2. 分析现有工程：用上文「代码分析规则」让模型输出模块结构、既有支付通道实现、Token 获取与异常模型等，明确接入点与复用边界。

3. 生成实现代码：在聊天中使用结构化 Prompt（脱敏后的模块名示例）：

## 目标
为 `order-pay-infrastructure` 模块的 `paychannel.mis` 包开发银联智能 POS 机的功能接口，包括消费指令、退货指令、撤销指令和支付结果查询接口，确保实现符合项目规范并复用已有逻辑。

## 背景
- 项目模块：`order-pay-infrastructure`，位于 `paychannel.mis` 包。
- 已有参考服务：`BindDevicePosServiceImpl`，包含访问令牌（Token）获取逻辑。
- 官方文档：`@5.3 POS 机交易指令接口.md`，定义了 POS 设备接口的请求和响应规范。
- 项目已抽象公共接口，需遵循统一异常处理、日志记录和入参/出参模型设计规范。

## 要求
1. **接口实现**：
   - 严格按照官方文档 `@5.3 POS机交易指令接口.md`，实现以下接口：
     - 消费指令：实现 `RequestPayService` 接口。
     - 退货指令：实现 `RequestRefundService` 接口。
     - 撤销指令：实现 `CancelPayService` 接口。
     - 支付结果查询：实现 `FindPaymentStatusService` 接口。
   - 确保实现类遵循接口契约，包含必要的请求和响应处理逻辑。
2. **遵循项目规范**：
   - 统一请求和响应格式，便于日志记录和监控。
   - 遵循现有异常处理机制，抛出标准化的异常。
   - 遵循入参/出参模型设计规范，确保数据结构一致性。
3. **代码组织**：
   - 将实现类放置在 `order-pay-infrastructure` 模块的 `paychannel.mis` 包下。
   - 为每个功能接口创建独立的实现类，命名清晰（如 `UnionPayRequestPayServiceImpl`）。

流程闭环：文档结构化 → 上下文分析 → 规范约束下的代码生成；同类对接可反复复用。

---

七、总结与迭代建议

• Prompt 与 Rules 不是一次写完就结束，应随项目、规范与模型版本持续 review。
• 模型升级后，用固定「金样例」任务回归测试输出是否漂移。
• .mdc 当作活文档，与迭代节奏一起演进；复杂规则拆文件，控制单文件体量。

从「写每一行代码」到「定义意图与边界」，工程师的价值更多体现在问题定义、架构取舍与质量门禁；AI 负责在清晰约束下放大执行效率。

---

参考 ：Cursor 官方文档、Prompting Guide；附录 F 已整段并入 Domain / Infrastructure / 策略模式三份 .mdc 正文。