Files
ai-proj-helper/skills-req/req-prd-plugin/skills/SKILL.md
T
johnQ 237631147a chore(skill): 清理全部 23 条历史校验警告
- 11 个超 20KB 的 SKILL.md 拆分,大章节移入 references/details.md
- 7 处非标准字段(arguments/user_invocable)移入 metadata
- 修 req-dev 4 条相对链接;validate 跳过行内代码避免 ![](...) 误报
- validate-skills.py: 23 warns -> 0 warns,0 errors
2026-10-31 22:21:07 +08:00

561 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: req-prd
description: 产品设计与需求管理。用于 PRD、需求分析、用户故事、功能设计和原型规划,并将正式需求文档双写到本地仓库与 ai-proj Task Document。
---
## 概述
本技能用于辅助产品设计和需求管理工作,包括:
- PRD 文档编写与管理
- 需求分析与优先级排序
- 用户故事创建
- 功能设计与规划
- 与 ai-proj 任务系统集成
**插件扩展**:
- `req-compare` — 对比式 PRD 编写(系统平移/竞品借鉴时激活)
- `req-prototype` — UI 模块在 PRD/缺陷收敛后生成、上传并关联 HTML 原型
- `defect-analysis` — 设计访谈确认后,对最新版 PRD 反复审计和修订直至收敛
## 产品需求文档双写门禁
本技能创建或修改的所有正式需求文档都必须同时保存到:
1. 当前产品仓库的本地 Markdown 文件;
2. Requirement 对应角色任务的 ai-proj Task Document。
适用文档至少包括原始诉求/讨论记录、PRD、缺陷优化记录、原型版本与评审记录。Requirement description 只保存已确认的讨论摘要,不能替代 Task Document。
### 路径与任务映射
优先遵循仓库已有文档目录和命名约定;没有约定时使用:
| 文档 | 本地默认路径 | ai-proj 任务角色 |
|------|--------------|------------------|
| 需求讨论记录 | `docs/product/{REQ-ID}-{slug}-discussion.md` | `documentation` |
| PRD(含缺陷修订和原型回填) | `docs/product/{REQ-ID}-{slug}-prd.md` | `prd` |
同一 Requirement、同一角色只维护一个当前任务文档。不得把本地文件路径当成 ai-proj 持久化,也不得只把远程 Task Document 导出一次后继续单边修改。
### 每次写入协议
1. 修改前同时读取本地文件与 ai-proj Task Document;任一不存在则基于另一份初始化,二者都不存在才新建空模板;
2. 若两份内容不一致,比较文档 ID、版本、更新时间和内容摘要,保留双方未知内容并显式合并;无法安全合并时停止并请用户选择,禁止静默覆盖;
3. 先用安全文件编辑方式写入本地 Markdown,再创建或更新对应 Task Document;
4. 写后重新读取两端,计算或比较内容摘要,确认正文一致,并记录本地路径、task_id、document_id、version/updated_at;
5. 任一端写入或复读失败都属于未完成的部分写入:保留已成功一端用于恢复,立即报告并停止后续阶段,不得宣称“已保存”“已收敛”或提交评审。
问答每一轮、每次 PRD 修订、每轮 defect 处置和每次原型回填都执行该协议;不能等到流程结束再一次性补传。
## 模块设计访谈模式
设计模块、系统、跨域流程,或目标/边界/业务规则尚未确定时,必须先执行问答式设计访谈,不得直接补全假设后生成 PRD。用户明确要求“你问我答”时也进入此模式。范围小、规则已完整确认的需求可以直接编写 PRD。
进入此模式后,**完整读取并执行** [references/design-interview-and-defect-loop.md](references/design-interview-and-defect-loop.md)。该协议定义:
- 每轮只问一个会改变方案的关键问题;
- 将问题、AI 建议、用户原话、决策和未决项逐轮写入 ai-proj 需求的讨论文档;
- 讨论结论经用户确认后,才能创建或更新 PRD;
- 使用 `defect-analysis` 对最新版 PRD 执行“审计 → 修订 → 全量重审”循环;
- UI 模块在 PRD 收敛后使用 `req-prototype` 生成独立 HTML 原型、上传关联 Requirement、回填 PRD 并完成可访问性与关键状态校验;
- 原型评审改变产品行为时,回到问答、PRD 修订和 `defect-analysis` 全量重审,再生成新原型版本;
- 讨论文档缺失、写入失败、用户未确认、原型未验证,或仍有未处置的致命/高严重度缺陷时,不得宣称设计完成或提交评审。
## HTML 原型完成闸门
模块包含用户界面、用户操作流程或可视状态时,HTML 原型是产品设计交付物,不是评审后的可选补充。默认执行 `/req prototype upload [REQ-ID]`,具体生成、上传、iframe 回填和验证规则由 `req-prototype` 定义。
必须满足:
1. 原型基于最新版、已完成缺陷收敛的 PRD,并记录 PRD 文档标识、版本或内容摘要;
2. 覆盖核心入口、主流程以及 PRD 明确要求的空态、失败态、无权限态和确认/撤销反馈;
3. 将本地 HTML 源文件通过 ai-proj 上传到 OSS;上传后重新读取 Requirement,确认 OSS URL/版本已关联,并验证 URL 可访问、iframe 可展示、核心交互可操作;
4. 将 iframe、原型版本、版本说明和验证结果双写到本地 PRD 与 prd 角色 Task Document,并把生成、反馈、修订和确认双写到本地讨论记录与 documentation 任务文档;
5. 用户明确确认最终 PRD 与原型表达的是同一方案。
纯后端、批处理、基础设施等确实没有用户界面的模块可以跳过,但必须在讨论文档和 PRD `4.2` 中记录“无 UI,原型不适用”的理由及用户确认,不得静默省略。
## 客户原话原则(REQ-20260416-0017 P1-8)
**编写 PRD 时必须包含「客户原始诉求」章节(模板 1.4),保留客户/业务方原话,不做 AI 加工。**
**为什么**:
- 产品经理转述会失真(借鉴自 devflow-claude 的"客户场景"设计)
- 后续争议追溯时有据可查
- 团队成员看到原话能建立同理心
**填写规范**:
- 原话用 Markdown `> 引用块` 包裹,区分于 AI 加工内容
- 标注提出人、时间、出处(会议/邮件/聊天)
- 特殊约束(时间/合规/预算)必须保留
---
## 对比式 PRD 编写
> 系统平移、竞品借鉴、版本升级时,使用 `req-compare` 插件进行对比分析。
> 该插件包含完整的对比工作流、对比式 PRD 模板和竞品分析模板。
**触发方式**:当需求涉及参考系统时,req-prd 自动推荐激活 req-compare 插件。
---
## PRD 文档模板
### 标准 PRD 结构
```markdown
# [产品/功能名称] PRD
## 1. 概述
### 1.1 背景
[为什么需要这个功能?解决什么问题?]
### 1.2 目标
- 业务目标:[量化的业务指标]
- 用户目标:[用户能获得什么价值]
- 技术目标:[技术层面要达成什么]
### 1.3 成功指标
| 指标 | 当前值 | 目标值 | 衡量方式 |
|------|--------|--------|----------|
| ... | ... | ... | ... |
### 1.4 客户原始诉求 ⭐ 强制保留
> **重要**:记录客户/业务方提出需求时的**原始描述**,**不做 AI 加工、不总结、不转述**。
> 保留原话是为了后续溯源"我们当初为什么做这个"有据可查,避免产品经理转述失真。
- **场景1**(提出人:xxx / 时间:yyyy-mm-dd):
> "原始描述引用..."
- **场景2**:
> "原始描述引用..."
**补充信息**(可选):
- 会议/邮件/聊天记录链接
- 客户特殊约束(如"必须在 Q2 前上线")
### 1.5 现有实现与复用盘点 ⭐ 强制
> **目的**:防止把「已经有的能力」当成新增来估工和开发(真实事故:DS Bot 早已有头像上传/裁剪功能,PRD 仍按新建估工)。
> **检索证据**:每条都要给 `file:line`(或 grep 命令 + 命中结果),不接受「凭印象认为没有」。
| 能力点 | 现有实现(file:line) | 结论 | 说明 |
|--------|----------------------|------|------|
| 头像上传/裁剪 | `ds-bot/src/client/bot-settings.js:xx` | 复用 | 只改存储落点与主体 |
| …(本次涉及的每个能力点都要有一行) | | | |
**硬规则**:
- 结论是 **复用 / 改造** 的,估工只算「接入差异」,不许按全新功能算。
- 结论是 **新增** 的,必须写「为什么现有实现不能满足」。
- 标「未排查」或没有 `file:line` 的 PRD **不得提交评审**;独立复查人(非 PRD 作者)要用 grep 复核并在 note 留证据。
## 2. 用户分析
### 2.1 目标用户
[用户画像描述]
### 2.2 用户痛点
1. [痛点1]
2. [痛点2]
### 2.3 用户场景
[场景描述]
## 3. 功能需求
### 3.1 功能清单
| 功能 | 优先级 | 描述 | 验收标准 |
|------|--------|------|----------|
| ... | P0/P1/P2 | ... | ... |
### 3.2 功能详细说明
#### [功能1]
- 功能描述:
- 触发条件:
- 业务规则:
- 异常处理:
## 4. 交互设计
### 4.1 用户流程
[流程图或步骤描述]
### 4.2 界面原型
> UI 模块使用 `/req prototype upload [REQ-ID]` 基于最新版 PRD 生成并上传 HTML 原型。
> 原型必须用 iframe 展示;Stitch 可作为视觉探索的可选输入,不能代替最终 HTML 原型闭环。
**原型基线**:
- PRD 文档/版本:...
- 原型版本与说明:...
- Requirement 关联状态:已验证 | 未验证
- 可访问性/关键交互验证:...
<iframe src="[prototype_url]"
width="100%" height="600" frameborder="0"
style="border-radius:8px;border:1px solid #e5e7eb;">
</iframe>
[无 UI 模块填写:原型不适用的理由、讨论记录位置和用户确认原话]
## 5. 技术要求
### 5.1 性能要求
- 响应时间:
- 并发量:
- 数据量:
### 5.2 安全要求
- 权限控制:
- 数据安全:
### 5.3 兼容性要求
- 浏览器:
- 设备:
## 6. 上线计划
### 6.1 里程碑
| 阶段 | 内容 | 完成标准 |
|------|------|----------|
| ... | ... | ... |
### 6.2 灰度策略
[灰度发布计划]
## 7. 验收标准 ⭐ 强制包含 VP 三件套
> **规则(源自 REQ-20260421-0002)**:每条 AC 必须附带 VP-Data / VP-Steps / VP-Pass,缺一项评审不通过。
### AC1: [验收条件标题]
**目标**:[一句话描述期望结果]
**VP-Data(前置测试数据)**:
- 环境:localhost / production(二选一,明确注明)
- 数据:[字段、值、状态,例如:需求状态=approved,关联任务 3 个,task_project_id 非空]
- 建数据方式:[curl localhost:8080/... 或 MCP 工具,禁止混用]
**VP-Steps(验证步骤)**:
1. [工具 + 操作,例如:agent-browser open http://localhost:3000/xxx]
2. [检查指标,例如:eval `document.querySelector('.xxx').textContent`]
3. [确认值,例如:返回值包含"期望字符串"]
**VP-Pass(通过判定)**:
- ✅ [具体期望值,例如:eval 返回数组长度 = 3]
- ✅ [第二个判定条件]
- ❌ [明确的不通过条件,例如:仅靠代码分析得出结论 = 不通过]
---
### AC2: [第二条验收条件]
**目标**:...
**VP-Data**:...
**VP-Steps**:...
**VP-Pass**:
- ✅ ...
- ❌ ...
## 8. 风险评估
| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| ... | 高/中/低 | 高/中/低 | ... |
## 9. 附录
- 相关文档链接
- 参考资料
```
---
## 需求优先级框架
### RICE 评分法
| 维度 | 说明 | 评分范围 |
|------|------|----------|
| Reach (触达) | 影响多少用户 | 1-10 |
| Impact (影响) | 对用户的影响程度 | 0.25-3 |
| Confidence (信心) | 估算的置信度 | 0-100% |
| Effort (工作量) | 需要的人天数 | 实际工作量 |
**计算公式**: `RICE = (Reach × Impact × Confidence) / Effort`
### 优先级定义
| 优先级 | 含义 | 处理方式 |
|--------|------|----------|
| P0 | 阻塞性需求 | 必须立即处理 |
| P1 | 核心需求 | 本迭代必须完成 |
| P2 | 重要需求 | 尽量本迭代完成 |
| P3 | 优化需求 | 有余力时处理 |
---
## 需求粒度判断(REQ-20260416-0017 P1-12)
**创建需求前,AI 必须先对标题做粒度预判。** 借鉴 devflow-claude `/req:split`。
### 核心问题
> **"这个需求完成后,用户能感知到一个完整的功能变化吗?"**
> - 能 → 粒度合适
> - 不能(太大或太小)→ 需调整
### 粒度参考表
| 标题示例 | 粒度 | 建议 |
|---------|------|------|
| "用户积分系统"(含规则+查询+兑换+排行) | 太大 | 拆为 4 个需求 |
| "用户积分-积分规则管理"(含 CRUD+校验) | 合适 | 直接创建 |
| "用户积分-新增积分接口"(仅一个 API) | 太小 | 合并到功能级需求,或用任务(task) |
| "用户积分-新增 model 层"(按技术层拆) | 错误 | 按功能拆,不按技术层拆 |
### AI 自动检测规则
**标题过宽信号**(建议拆分):
- 含"系统"/"模块"/"平台"/"管理"等宏观词
- 描述中功能点 > 5 个
- 预估涉及文件 > 15 个
**标题过窄信号**(建议合并或改 task):
- 含"新增XX接口"/"修改XX字段"/"加一个按钮"
- 单个 CRUD 操作
- 预估涉及文件 ≤ 2 个
**错误拆分信号**(按技术层拆了):
- 标题含"model 层"/"service 层"/"handler 层"/"前端样式"
- 同一业务被拆为"后端接口"和"前端页面"两个独立需求
### 执行时机
1. **创建需求时**(`/req new` 或 `create_requirement`):检查标题,给出建议
2. **编辑需求时**:功能清单超 8 项时提醒"是否应拆分"
3. **独立评估**:用 `/req split <标题>` 预判粒度
### 三种输出
1. **粒度合适** → 正常创建
2. **建议拆分** → 列出子功能建议,用户确认后批量创建
3. **建议改 task/QUICK** → 提示"这个用任务更合适"
### 已有需求扩展功能的决策
> **"去掉这个新功能点,原需求还能独立交付吗?"**
> - 能 → 新建需求
> - 不能 → 修改原需求(`/req edit`)
| 场景 | 建议 |
|------|------|
| 新功能是原需求的自然延伸 | 修改原需求 |
| 新功能可独立上线 | 新建需求 |
| 原需求已完成/归档 | 必须新建 |
| 原需求开发中,新增会影响已有代码 | 新建(防范围蔓延) |
### 前后端拆分规则
```
✅ 正确:
REQ-001 用户积分规则管理-后端(含 CRUD 全部接口)
REQ-002 用户积分规则管理-前端(含 CRUD 全部页面)
❌ 错误:
REQ-001 用户积分规则-新增接口
REQ-002 用户积分规则-查询接口
REQ-003 用户积分规则-修改接口
```
---
## 用户故事编写
### 标准格式
```
作为 [用户角色],
我想要 [功能/目标],
以便 [获得的价值/原因]。
验收标准:
- Given [前置条件]
- When [用户行为]
- Then [预期结果]
```
### 示例
```
作为 仓库管理员,
我想要 扫码快速入库,
以便 提高入库效率、减少手动输入错误。
验收标准:
- Given 已有采购单且货物到达
- When 扫描货物条码
- Then 自动匹配采购单并显示入库确认界面
```
### INVEST 原则检查
| 原则 | 含义 | 检查点 |
|------|------|--------|
| I - Independent | 独立的 | 故事间无依赖 |
| N - Negotiable | 可协商 | 非固定规格 |
| V - Valuable | 有价值 | 交付业务价值 |
| E - Estimable | 可估算 | 能估算工作量 |
| S - Small | 足够小 | 可在迭代内完成 |
| T - Testable | 可测试 | 有明确验收标准 |
---
## 与 ai-proj 集成
### 需求管理工具
使用 ai-proj MCP 工具管理需求:
```bash
# 创建需求
mcp__ai-proj__create_requirement
- title: "需求标题"
- description: "需求描述"
- category: feature/bug/improvement/documentation/other
- priority: low/medium/high
- projectId: 项目ID
# 查看需求列表
mcp__ai-proj__list_requirements
- status: draft/pending/reviewing/approved/rejected/archived
- priority: low/medium/high
# 需求与任务关联
mcp__ai-proj__link_tasks_to_requirement
- requirementId: 需求ID
- taskIds: [任务ID列表]
```
### 任务分解流程
1. **创建需求** → `create_requirement`
2. **需求评审** → `submit_requirement` → `approve/reject_requirement`
3. **分解任务** → `create_task` / `create_subtask`
4. **关联任务** → `link_tasks_to_requirement`
5. **跟踪进度** → `get_requirement_tasks` / `get_requirement_statistics`
### 文档管理
以下 MCP 操作只完成 ai-proj 侧写入;每次调用前后都必须按“产品需求文档双写门禁”同步并校验本地 Markdown。
```bash
# 创建 PRD 文档并关联任务
mcp__ai-proj__create-and-attach
- taskId: 任务ID
- content: PRD 文档内容 (Markdown)
- title: 文档标题 (可选)
# 更新 PRD 文档
mcp__ai-proj__update_task_document
- taskId: 任务ID
- content: 更新后的内容
# 导出 PRD 到文件
mcp__ai-proj__export_task_document_to_file
- taskId: 任务ID
```
导出命令不能代替双写校验:导出后仍需确认目标路径符合仓库约定、正文与 Task Document 当前版本一致,且没有覆盖本地新增内容。
---
## 竞品分析
> 竞品分析模板已移至 `req-compare` 插件。涉及竞品对比时自动激活。
---
## 产品指标体系
### 北极星指标选择
| 产品类型 | 典型北极星指标 |
|----------|----------------|
| 电商 | GMV / 订单量 |
| SaaS | MRR / 活跃用户数 |
| 社交 | DAU / 消息数 |
| 工具 | 完成任务数 / 使用时长 |
### 指标分层
```
北极星指标
├── 一级指标(核心业务指标)
│ ├── 二级指标(过程指标)
│ │ └── 三级指标(功能指标)
```
### 常用指标
| 类型 | 指标 | 计算方式 |
|------|------|----------|
| 获客 | 新用户数、获客成本 | 注册数 / 推广费用 |
| 激活 | 激活率、首日留存 | 完成核心动作 / 注册数 |
| 留存 | 次日/7日/30日留存 | 回访用户 / 新增用户 |
| 收入 | ARPU、付费率 | 收入 / 用户数 |
| 传播 | 推荐率、K因子 | 邀请数 / 用户数 |
---
## 常用工具
### 原型设计
- **HTML upload(默认交付)** — `/req prototype upload` 生成可交互独立 HTML,上传后以 iframe 关联 Requirement 和 PRD
- **Stitch** (Google AI) — `/req prototype` 视觉探索与多屏草图,可作为 HTML 原型输入但不替代最终闭环
- Figma — 手动精细设计
- Sketch
- Axure
### 流程图
- draw.io
- ProcessOn
- Mermaid (Markdown)
### 数据分析
- Metabase
- Google Analytics
- Mixpanel
### 项目管理
- ai-proj (内部)
- JIRA
- Linear
---
## 最佳实践
1. **需求先行** - 先理解问题,再设计方案
2. **用户视角** - 始终从用户角度思考
3. **数据驱动** - 用数据验证假设
4. **迭代优化** - 小步快跑,持续改进
5. **跨团队协作** - 早期与技术、设计团队对齐
6. **文档沉淀** - 及时记录决策和变更
---
## 安全与合规
- 用户隐私保护 (GDPR/个人信息保护法)
- 数据安全分级
- 敏感操作审计
- 权限最小化原则
---
## 详细内容
以下章节已移到 [references/details.md](references/details.md):
- 功能设计流程
- 设计检查清单
- Memory 隔离规则(强制,源自 devflow-claude 借鉴)