AI 编程的 Prompt 工程：如何写出高质量指令

---

一、为什么 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 就是指令，指令越清晰，执行越精准。