koi-prd-generator

name	koi-prd-generator
description	生成产品需求文档（PRD）。用于规划功能、启动新项目。触发词：创建prd、写prd、规划功能、产品需求文档。
user-invocable	true

Koi PRD 生成器技能

创建清晰、可操作且适合实施的产品需求文档。

---

工作内容

1. 接收用户的功能描述
2. 提出必要的关键澄清问题（带字母选项）
3. 根据答案生成结构化的 PRD
4. 保存到 prd-context/prd-files/prd-[功能名称].md

重要：

• 不要开始实施。只创建 PRD。
• 如果 prd-context/ 目录不存在，尝试自动创建。
• 如果创建目录失败，提示用户手动创建 prd-context/ 目录。

---

技术栈信息

技术栈信息由 prd-pipeline 传递，无需在本技能中询问。

步骤 1：澄清问题

第一轮询问

1. 请描述你需要的功能：

后续轮次询问

1. 请描述你需要修正的部分：
2. 请提供更多的细节：

---

步骤 2：PRD 结构

使用以下部分生成 PRD：

1. 引言/概述

简要描述功能及其解决的问题。

2. 目标

具体的、可衡量的目标（项目符号列表）。

Branch 名称： 在目标部分下方添加 branch 名称，格式如：branchName: prd/pre-review-management

3. 用户故事

每个故事需要：

• 标题： 简短的描述性名称
• 描述： "作为一名 [用户]，我希望 [功能] 以便 [收益]"
• 验收标准： 可验证的"完成"清单
• 依赖： （可选）前置故事编号，如 "US-001"
• 优先级： 高/中/低

故事拆分原则（关键）：

• 每个故事必须足够小，能在一次 AI 会话中完成（15-30 分钟工作量）
• 一个故事只做一件事：要么 UI、要么逻辑、要么数据存储
• 反面教材："创建完整的用户管理系统"（太大，需要拆分）
• 正面教材："添加用户姓名字段到表单"、"实现邮箱验证逻辑"

拆分示例：

过大故事	应拆分为
"创建预审记录（表单 + 上传 + 验证）"	①创建表单页面 ②实现附件上传 ③表单验证逻辑
"查询和搜索（筛选 + 关键词 + 分页 + 排序）"	①列表展示与分页 ②多条件筛选 ③关键词搜索 ④列表排序
"编辑功能（界面 + 预填充 + 附件 + 历史）"	①编辑表单与预填充 ②附件增删 ③编辑历史记录

格式：

### US-001: [标题]
**描述：** 作为一名 [用户]，我希望 [功能] 以便 [收益]。
**依赖：** US-000（可选，如数据库设计故事）
**优先级：** 高

**验收标准：**
- [ ] 具体、可验证的标准（包含字段名、类型、格式、数量等具体信息）
- [ ] 另一个标准（避免"正确工作"等模糊描述）
- [ ] 类型检查/lint 通过
- [ ] **[仅限 UI 故事]** 在浏览器中验证

验收标准写作要求（关键）：

• ❌ 坏的写法："表单包含必要字段"、"支持上传附件"、"显示成功提示"
• ✅ 好的写法：
  • "表单包含以下字段：预审日期 (date picker)、申请人 (文本输入，最多 50 字)、状态 (下拉选择：待审批/已通过/已拒绝)"
  • "支持上传 pdf/doc/docx/jpg/png 格式附件，单文件不超过 10MB，最多 5 个附件"
  • "保存成功后，页面顶部显示绿色 toast 提示'保存成功'，3 秒后自动消失"
  • "编辑保存后，在操作日志表中插入一条记录，包含：操作人 ID、操作时间、修改前后的字段值差异"

依赖说明要求：

• 新项目第一个故事必须是：项目 scaffold + 数据库/数据模型设计
• 数据库故事是其他所有故事的依赖（US-000）
• UI 故事依赖对应的后端 API 故事
• 如果一个功能需要多个故事完成，明确标注依赖关系

对于任何有 UI 更改的故事： 始终包含"在浏览器中验证"作为验收标准。这确保了前端工作的可视化验证。

4. 功能需求

具体功能的编号列表：

• "FR-1：系统必须允许用户..."
• "FR-2：当用户点击 X 时，系统必须..."

要明确且不含糊。

功能需求与用户故事对应检查：

• 每个 FR 必须有对应的用户故事（US）
• 如果 FR 描述的是权限控制、审计日志、响应式布局等非功能性需求，需要创建对应的 US
• 检查清单：
  • FR-1 ~ FR-N 都有对应的 US
  • 权限控制有对应的 US（如需要）
  • 审计日志有对应的 US（如需要）
  • 响应式布局有对应的 US（如需要）

5. 非目标（范围外）

此功能不包括什么。这对于管理范围至关重要。

要求：

• 对于支持的功能（如附件上传），要明确说明是否包含相关衍生功能（如附件预览）
• 示例：
  • "支持附件上传，但不支持在线预览"
  • "支持发送短信通知，但不支持电话呼叫"

6. 设计注意事项（可选）

• UI/UX 要求
• 如果有 mockup 链接
• 要重用的相关现有组件

6.5 依赖说明（关键）

新项目必须包含：

• 项目 scaffold 故事（第一个故事）
• 数据库/数据模型设计故事（US-000）

第三方依赖说明：

• 任何新引入的包/库必须在验收标准中注明安装命令
• 示例：
  • "安装 Excel 解析库：npm install xlsx"
  • "安装文件上传处理：npm install multer"
  • "安装 UI 组件库：npm install antd"

7. 技术注意事项（可选）

• 已知约束或依赖
• 与现有系统的集成点
• 性能要求

技术栈明确要求（关键）：

• 必须明确指定具体技术栈，不能使用"等"模糊描述
• ❌ 坏的写法："前端使用现代化框架（React/Vue 等）"
• ✅ 好的写法：
  • "前端：React 18 + TypeScript + Ant Design 5"
  • "后端：Node.js 20 + Express 4 + PostgreSQL 15"
  • "状态管理：Zustand"
  • "构建工具：Vite 5"

8. 成功指标

如何衡量成功？

• "将完成 X 的时间减少 50%"
• "将转化率提高 10%"

9. 开放问题

剩余的问题或需要澄清的领域。

要求：

• 开放问题应该在 PRD 定稿前尽量解答
• 问题描述要完整，不要有截断或不完整的句子
• 如果问题影响实现，需要标注优先级

---

为初级开发者编写

PRD 读者可能是初级开发者或 AI 代理。因此：

• 要明确且不含糊
• 避免术语或加以解释
• 提供足够的细节来理解目的和核心逻辑
• 编号要求以便轻松引用
• 在有帮助的地方使用具体示例

---

输出

• 格式： Markdown（.md）
• 固定位置： prd-context/prd-files/prd-[功能名称].md
• 目录处理： 如果 prd-context/ 目录不存在，尝试自动创建；如果创建失败，提示用户手动创建
• 文件名规范： 使用小写连字符格式，如 prd-login-system.md

---

PRD 示例

以下是一个符合最佳实践的 PRD 示例（简化版）：

# PRD：任务优先级系统

## 引言

为任务添加优先级，以便用户能够专注于最重要的事项。

## 目标

- 允许为任何任务分配优先级（高/中/低）
- 提供不同优先级之间的清晰视觉区分
- 启用按优先级筛选和排序
- 默认新任务为中优先级

**branchName:** prd/task-priority-system

## 用户故事

### US-000：数据库设计
**描述：** 作为一名开发者，我需要设计数据库表结构，以便存储任务优先级数据。
**依赖：** 无（第一个故事）
**优先级：** 高

**验收标准：**
- [ ] 创建 tasks 表，包含字段：id(uuid), title(text), priority('high'|'medium'|'low', 默认'medium'), created_at(timestamp)
- [ ] 成功生成并运行迁移：`npm run db:migrate`
- [ ] 类型定义文件 `src/types/task.ts` 包含 Priority 类型：'high' | 'medium' | 'low'
- [ ] 类型检查通过

### US-001：在任务卡片上显示优先级徽章
**描述：** 作为一名用户，我希望一目了然地看到任务优先级，以便知道什么需要首先关注。
**依赖：** US-000
**优先级：** 高

**验收标准：**
- [ ] 每个任务卡片右侧显示彩色优先级徽章
- [ ] 颜色映射：红色 (#ff4d4f)=高，橙色 (#faad14)=中，灰色 (#d9d9d9)=低
- [ ] 徽章尺寸：24x24px，圆角 4px
- [ ] 无需悬停或点击即可看到优先级
- [ ] 安装 Ant Design：`npm install antd`
- [ ] 类型检查通过
- [ ] 在浏览器中验证

### US-002：在任务编辑中添加优先级选择器
**描述：** 作为一名用户，我希望在编辑任务时更改任务的优先级。
**依赖：** US-000
**优先级：** 中

**验收标准：**
- [ ] 任务编辑模态框包含优先级下拉菜单（使用 Ant Design Select 组件）
- [ ] 下拉选项：高优先级、中优先级、低优先级
- [ ] 显示当前选中的优先级
- [ ] 选择更改后立即保存到数据库
- [ ] 保存成功后显示绿色 toast 提示"保存成功"，3 秒后自动消失
- [ ] 类型检查通过
- [ ] 在浏览器中验证

### US-003：按优先级筛选任务
**描述：** 作为一名用户，当我很专注时，我希望筛选任务列表以仅查看高优先级的项目。
**依赖：** US-000
**优先级：** 中

**验收标准：**
- [ ] 任务列表顶部包含筛选下拉菜单，选项：全部 | 高优先级 | 中优先级 | 低优先级
- [ ] 筛选条件持久化在 URL 参数中（如 ?priority=high）
- [ ] 当没有匹配的任务时显示空状态："暂无任务"
- [ ] 筛选改变时不使用页面刷新
- [ ] 类型检查通过
- [ ] 在浏览器中验证

## 功能需求

- FR-1：向 tasks 表添加 `priority` 字段（'high' | 'medium' | 'low'，默认'medium'）
- FR-2：在每个任务卡片右侧显示彩色优先级徽章
- FR-3：在任务编辑模态框中包含优先级下拉选择器
- FR-4：向任务列表顶部添加优先级筛选下拉菜单
- FR-5：在每个状态列内按优先级排序（高→中→低）

## 非目标

- 没有基于优先级的通知或提醒
- 没有基于到期日期的自动优先级分配
- 子任务没有优先级继承
- 不支持批量修改优先级

## 技术栈

- 前端：React 18 + TypeScript + Ant Design 5
- 状态管理：Zustand
- 构建工具：Vite 5
- 数据库：PostgreSQL 15

## 成功指标

- 用户可以在不到 2 次点击内更改优先级
- 高优先级任务在列表顶部立即可见
- 任务列表性能无回归（加载时间 < 500ms）

## 开放问题

- 优先级是否应该影响列内的任务排序顺序？（建议：是，高→中→低）
- 是否需要添加键盘快捷键来快速修改优先级？（建议：后续迭代添加）

---

保存前检查清单

• 用带字母的选项提出了澄清问题
• 结合了用户的答案
• 用户故事足够小（每个故事 15-30 分钟工作量）
• 用户故事有明确的依赖关系标注
• 验收标准具体可验证（包含字段名、类型、格式、数量等）
• 每个 UI 故事包含"在浏览器中验证"
• 功能需求与用户故事一一对应
• 技术栈明确指定（无"等"模糊描述）
• branchName 已定义
• 第三方依赖包含安装命令
• 非目标部分说明了衍生功能（如附件是否支持预览）
• 开放问题描述完整，无截断句子
• 保存到 prdFiles/prd-[功能名称].md