PRD 驱动开发

PRD 驱动开发（Spec-First Development）是一种将产品需求文档作为 AI 编程的核心输入的工作流。通过结构化的需求描述，AI 能更准确地理解意图，生成符合预期的代码，大幅减少反复沟通的成本。

为什么需要 PRD 驱动

传统 AI 编程的问题：

• 边想边写，AI 缺乏全局视野，容易产生局部最优的错误设计
• 需求变更时，AI 不了解原始意图，难以做出正确判断
• 多轮对话后，早期的约束和决策会被"遗忘"

PRD 驱动的优势：

• 需求文档作为持久化上下文，任何时候都可以重新喂给 AI
• 强迫开发者在编码前想清楚需求，减少返工
• 团队协作时，所有人对齐同一份 spec

---

PRD 模板结构

以下是适用于 AI 辅助开发的 PRD 模板：

# 功能名称：[简短描述]

## 1. 背景与目标
**问题陈述**：当前存在什么问题？
**解决方案**：本功能如何解决？
**成功指标**：如何判断功能成功？

## 2. 用户故事
作为 [用户角色]，
我希望 [做某件事]，
以便 [达到某个目标]。

## 3. 功能范围
### 必须实现（Must Have）
- [ ] 功能点 A
- [ ] 功能点 B

### 应该实现（Should Have）
- [ ] 功能点 C

### 暂不实现（Won't Have）
- 功能点 D（原因：...）

## 4. 技术规格
**接口设计**：API 端点、请求/响应格式
**数据模型**：数据库表结构或数据类型
**业务规则**：约束条件、验证逻辑、边界情况
**性能要求**：响应时间、并发量等

## 5. UI/UX 说明
**页面流程**：用户操作步骤
**错误状态**：各种错误的展示方式
**加载状态**：异步操作的交互反馈

## 6. 测试用例
**正常流程**：主路径测试
**异常处理**：错误路径测试
**边界情况**：极值、空值、并发等

---

完整 PRD 实例：用户评论系统

# 功能名称：课程评论与评分系统

## 1. 背景与目标
**问题陈述**：学员完成课程后没有渠道反馈学习体验，导致课程质量无法持续改进。
**解决方案**：为每门课程添加评论和星级评分功能。
**成功指标**：上线 30 天内，完课学员评论率 >20%。

## 2. 用户故事
- 作为学员，我希望在完成课程后提交评分（1-5 星）和文字评论，以便表达学习感受
- 作为学员，我希望看到其他人的评论，以便决定是否购买该课程
- 作为讲师，我希望回复学员评论，以便与学员互动
- 作为管理员，我希望删除违规评论，以便维护社区环境

## 3. 功能范围
### 必须实现
- [ ] 提交评论（含评分 + 文字，最多 500 字）
- [ ] 展示评论列表（分页，每页 10 条，按时间倒序）
- [ ] 显示课程平均评分和评论数量
- [ ] 每个学员每门课只能评论一次

### 应该实现
- [ ] 讲师回复评论
- [ ] 评论点赞
- [ ] 举报违规评论

### 暂不实现
- 评论图片上传（v2 版本考虑）
- AI 生成评论摘要（待评估）

## 4. 技术规格

### API 设计
POST   /api/courses/:courseId/reviews     # 提交评论
GET    /api/courses/:courseId/reviews     # 获取评论列表
DELETE /api/reviews/:reviewId             # 删除评论（管理员）
POST   /api/reviews/:reviewId/reply       # 讲师回复

### 请求/响应格式
// 提交评论请求
{
  "rating": 5,          // 1-5 整数
  "content": "课程很好" // 10-500 字符
}

// 评论列表响应
{
  "data": {
    "reviews": [...],
    "pagination": { "page": 1, "total": 42 },
    "summary": { "average": 4.6, "count": 42 }
  }
}

### 数据模型
reviews 表：
- id: UUID PK
- course_id: UUID FK(courses)
- user_id: UUID FK(users)
- rating: SMALLINT (1-5)
- content: VARCHAR(500)
- created_at: TIMESTAMP
- UNIQUE(course_id, user_id)  -- 防止重复评论

### 业务规则
- 只有完成课程（progress = 100%）的学员才能评论
- 评论内容需要经过敏感词过滤
- 删除评论后同步更新课程平均分缓存

## 5. UI/UX 说明
**评论入口**：课程完成页面展示评论表单（弹窗形式）
**评论列表**：课程详情页 Tab 中展示，默认显示最新评论
**错误状态**：
  - 未完成课程：提示"完成课程后才能评论"
  - 已评论过：展示已有评论，不显示提交表单
  - 提交失败：提示错误信息，保留输入内容

## 6. 测试用例
- 正常：完课学员提交 5 星评论，成功显示在列表
- 重复：同一学员再次提交，返回 409 错误
- 未完课：未完成学员提交，返回 403 错误
- 边界：content 为空、超过 500 字、rating 为 0 或 6
- 并发：同时提交 100 个评论，均正确写入

---

将 PRD 转化为 Prompt

有了 PRD，如何高效地转化为 AI 指令：

阶段一：生成数据模型

基于以下 PRD 中的数据模型规格，生成 Prisma schema：

[粘贴 PRD 第 4 节"数据模型"部分]

要求：
- 添加适当的索引（根据查询需求）
- 添加 updatedAt 字段
- 关系使用 @relation 明确声明

阶段二：生成 API 接口

基于以下 PRD，实现 POST /api/courses/:courseId/reviews 接口：

[粘贴完整 PRD]

实现要求：
1. 用 Zod 验证请求体（对应 PRD 第 4 节请求格式）
2. 检查用户是否完成课程（对应 PRD 业务规则 1）
3. 检查是否已评论（对应唯一约束）
4. 成功后更新课程平均分缓存（对应业务规则 3）
返回类型遵循 PRD 中的响应格式。

阶段三：生成测试

基于以下 PRD 的测试用例部分，为评论提交接口写 Vitest 集成测试：

[粘贴 PRD 第 6 节]

每个测试用例对应 PRD 中一条测试场景，
用 describe/it 组织，it 的描述直接使用 PRD 中的场景描述。

---

用户故事驱动开发

将用户故事转化为可执行的开发任务：

用户故事格式：
As a [role], I want [action], so that [benefit].

转化为 Prompt：

"实现以下用户故事：
作为讲师，我希望在评论列表中看到哪些是新评论（7天内未读），
以便优先处理最新的学员反馈。

技术实现要求：
- 后端：在 reviews 表添加 read_at 字段（讲师已读时间）
- API：GET /api/instructor/reviews 支持 unread=true 过滤
- 前端：未读评论显示红点角标
- 性能：讲师未读数量用 Redis 缓存，有新评论时更新"

---

Spec-First 工作流

1. 写 PRD
   ↓（将 PRD 存为 docs/specs/feature-name.md）

2. 技术方案评审
   "基于这份 PRD，分析技术实现方案，指出潜在风险"
   ↓

3. 分解任务
   "将 PRD 拆解为独立的开发任务，按依赖顺序排列"
   ↓

4. 逐任务实现
   "实现任务 1：[粘贴任务描述 + 相关 PRD 章节]"
   ↓

5. 验收测试
   "对照 PRD 第 6 节测试用例，验证实现是否满足所有要求"

提示：将 PRD 文件路径添加到 CLAUDE.md，或在每次对话开始时将 PRD 内容粘贴给 AI，确保 AI 始终有完整的需求上下文。