一、为什么 Prompt 工程如此重要？
AI 编程工具本质上是"对话式编程"。你说的每一句话，都是 AI 的输入信号。输入质量决定输出质量。
常见的低质量 Prompt：
帮我写个登录功能
结果： AI 给你一个 50 行的 demo，没有验证、没有安全处理、没有错误提示。
高质量 Prompt：
用 Next.js 14 App Router 实现用户登录功能：
1. 使用 bcrypt 加密密码
2. JWT token 存储在 httpOnly cookie
3. 表单验证：邮箱格式、密码至少8位含大小写数字
4. 错误处理：数据库连接失败、用户不存在、密码错误
5. 登录成功后跳转到 /dashboard
6. 参考 src/lib/auth.ts 的现有代码风格
结果： AI 给你一个完整、安全、可维护的登录模块。
二、高质量 Prompt 的五个要素
1. 明确技术栈和框架
❌ "写个 API" ✅ "用 FastAPI + SQLAlchemy + Pydantic 写一个 RESTful API"
2. 具体需求和边界条件
❌ "处理用户输入" ✅ "验证用户输入：XSS 过滤、SQL 注入防护、最大长度 1000 字符"
3. 代码风格和约束
❌ "写个工具函数" ✅ "写一个纯函数，无副作用，有完整的 TypeScript 类型定义，参考项目中 utils/format.ts 的风格"
4. 错误处理和边界情况
❌ "读取配置文件" ✅ "读取 config.json，处理：文件不存在、JSON 格式错误、缺少必需字段、权限不足等情况"
5. 上下文和参考
❌ "优化这段代码" ✅ "优化 src/services/userService.ts 的 getUserById 方法，保持接口不变，参考 src/services/productService.ts 的缓存实现方式"
三、实战案例对比
案例 1：生成数据模型
❌ 低质量：
帮我写个用户模型
✅ 高质量：
用 Prisma Schema 定义用户模型：
- id: 自增主键
- email: 唯一索引，带验证
- password: 加密存储，不返回给前端
- name: 可选
- avatar: URL 格式，可选
- role: 枚举 (USER, ADMIN, MODERATOR)，默认 USER
- createdAt, updatedAt: 自动时间戳
- 关联: 一对多 posts, comments；多对多 likedPosts
参考项目中其他模型的命名风格
案例 2：实现业务逻辑
❌ 低质量：
写个购物车功能
✅ 高质量：
实现购物车核心逻辑（TypeScript + 纯函数）：
功能：
1. addCartItem(cart, product, quantity) - 添加商品，已存在则累加数量
2. removeCartItem(cart, productId) - 移除商品
3. updateQuantity(cart, productId, quantity) - 更新数量，0 则移除
4. calculateTotal(cart) - 计算总价，考虑商品折扣
5. validateCart(cart, inventory) - 验证库存，返回不可购买商品
约束：
- 不可变数据，返回新对象
- 数量上限 99
- 价格精度用 decimal.js 处理
- 完整类型定义，导出所有类型
案例 3：重构代码
❌ 低质量：
优化这个函数
✅ 高质量：
重构 src/utils/dataParser.ts 的 parseUserData 函数：
当前问题：
- 200 行单函数，难以测试
- 多个 try-catch 嵌套
- 硬编码的魔法数字
重构目标：
1. 拆分为 5-7 个单一职责的小函数
2. 用 Result<T, E> 模式处理错误
3. 提取常量到顶部
4. 添加单元测试用例（在 __tests__/dataParser.test.ts）
保持：
- 公开 API 不变
- 处理逻辑不变
- 性能不下降
四、Cursor 专属技巧
1. @符号精准定位
@src/services/auth.ts 帮我添加 OAuth 登录支持
@docs/api.md 参考 API 文档实现这个接口
@src/types/index.ts 补充缺失的类型定义
2. Chat 模式深度讨论
/chat
我在设计一个权限系统，需要支持：
- 角色继承（admin > moderator > user）
- 资源级别权限
- 动态权限分配
帮我分析设计方案，给出数据模型和核心接口
3. Composer 多文件协作
@src/services/*.ts @src/models/*.ts
帮我实现用户关注功能：
- 关注/取消关注
- 获取关注列表
- 获取粉丝列表
- 互关检测
需要修改所有相关文件，保持类型一致
五、Claude Code 专属技巧
1. 项目级理解
# 让 Claude 理解整个项目结构
claude "分析这个项目的架构，列出核心模块和依赖关系"
# 针对性提问
claude "src/services/payment.ts 使用了哪些外部依赖？有什么潜在风险？"
2. 渐进式开发
# 第一步：设计
claude "设计一个缓存装饰器，支持 TTL、LRU、分布式锁"
# 第二步：实现
claude "根据刚才的设计，实现 src/decorators/cache.ts"
# 第三步：测试
claude "为 cache.ts 编写完整的单元测试"
3. 调试助手
claude "这个错误怎么解决？[粘贴完整错误信息]
相关代码：
[粘贴相关代码片段]
运行环境：Node.js 20, macOS 14"
六、Prompt 模板库
模板 1：新功能开发
实现 [功能名称]：
技术栈：[框架/库]
入口文件：[文件路径]
需求：
1. [具体需求1]
2. [具体需求2]
3. [具体需求3]
约束：
- [性能要求]
- [安全要求]
- [兼容性要求]
参考：
- [现有代码路径] 的风格
- [文档链接] 的规范
输出：
- [期望的文件结构]
- [需要更新的文件]
模板 2：Bug 修复
修复 Bug：[Bug 描述]
复现步骤：
1. [步骤1]
2. [步骤2]
期望行为：[正确行为]
实际行为：[错误行为]
相关代码：@src/path/to/file.ts
分析可能原因，给出修复方案，并添加回归测试
模板 3：代码审查
审查 @src/path/to/file.ts：
检查项：
- 安全漏洞（XSS、注入、敏感信息泄露）
- 性能问题（N+1 查询、内存泄漏）
- 代码质量（命名、注释、重复代码）
- 错误处理（边界情况、异常捕获）
- 类型安全（TypeScript）
输出格式：
- 问题列表（严重程度：高/中/低）
- 修复建议
- 重构建议
七、常见错误与纠正
| 错误 | 问题 | 纠正 |
|---|---|---|
| "写个功能" | 太模糊 | 明确技术栈、需求、约束 |
| "像 XXX 一样" | AI 不知道 XXX | 粘贴代码或描述具体特征 |
| "优化一下" | 没说优化什么 | 明确性能指标或代码质量目标 |
| "帮我看看" | 没说看什么 | 明确检查项和期望输出 |
| "简单写个" | AI 会真的简单写 | 即使简单也要说完整需求 |
八、进阶技巧
1. 思维链引导
实现用户注册功能，请按以下步骤思考：
1. 分析需求：需要哪些字段、哪些验证
2. 设计数据模型：字段类型、约束、索引
3. 设计 API 接口：请求/响应格式、错误码
4. 实现核心逻辑：验证、加密、存储
5. 添加测试用例：正常流程、边界情况、错误处理
每步完成后请说明，再继续下一步
2. 示例驱动
参考以下代码风格，实现订单取消功能：
示例代码：
```typescript
// src/services/refundService.ts
export async function processRefund(
orderId: string,
reason: RefundReason
): Promise<Result<Refund, RefundError>> {
// ...
}
要求：
- 同样的错误处理模式
- 同样的返回类型风格
- 同样的日志记录方式
### 3. 约束驱动
实现文件上传功能，必须满足：
性能约束：
- 单文件最大 10MB
- 支持断点续传
- 上传进度实时反馈
安全约束：
- 文件类型白名单
- 文件名 XSS 过滤
- 路径穿越防护
兼容约束：
- 支持 Chrome、Firefox、Safari
- 移动端适配
---
## 九、总结
Prompt 工程不是玄学，是一套可学习、可复用的方法论。
**核心原则：**
1. **具体 > 模糊**：告诉 AI 你想要什么，而不是让 AI 猜
2. **上下文 > 隔离**：给 AI 足够的背景信息
3. **约束 > 自由**：限制 AI 的发挥空间，避免"创意过度"
4. **迭代 > 一次**：不满意就继续对话，逐步逼近目标
**记住：** AI 编程工具是你的副驾驶，你才是机长。Prompt 就是指令，指令越清晰，执行越精准。
