forge-prd · git:20260717.95d1b1c · 2026-07-17 · sha256 40a39dfd84477d48
forge-prd git:20260717.95d1b1cA
Immutable. This exact content never changes and is served at /api/v1/blob/40a39dfd84477d48.
---
name: forge-prd
description: |
产品诊断与 PRD 迭代：诊断根因（设计缺陷/实现偏离/PRD 遗漏），必要时反驳需求，更新 PRD 并生成带异常态门禁的 Feature Spec。
触发方式：用户说"更新PRD"、"调整需求"、"迭代PRD"、"forge-prd"、描述产品问题、需要修改产品需求时。
---
> **文档落地路径**：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见
> `~/.claude/skills/forge-doc-policy/doc-paths.md`。
> **当前文档加载契约**：先读项目 `CLAUDE.md`、`docs/README.md`、`docs/INDEX.md` 和根级当前真相源；长 changelog 和 raw archive 只在追溯历史原因时加载。详见 `~/.claude/skills/_shared/current-doc-loading.md`。
# /forge-prd：产品诊断与 PRD 迭代管理器
## 流程总览
全程中文。每个步骤结束后暂停等待用户反馈。
```
用户描述问题/需求
│
▼
┌─ 第0步：定位 ──────────────────────────┐
│ Glob 搜索 PRD / CHANGELOG │
│ ├─ 找到 PRD → 迭代模式 │
│ ├─ 没找到 → [询问用户] 是否创建模式 │
│ └─ 没找到 CHANGELOG → 标记第4步新建 │
└──────────────────────────────────────────┘
│
▼
┌─ 第1步：理解现状 ─────────────────────────┐
│ 读 PRD + CHANGELOG + Agent(Explore)源码 │
│ 热点分析（模块修改频次） │
│ → [询问用户] 总结现状，确认理解是否正确 │
│ → [询问用户] 本次迭代需求是什么？ │
└─────────────────────────────────────────────┘
│
▼
┌─ 第2步：诊断与审查 ──────────────────────────┐
│ 自动判定层级：轻量 / 标准 / 深度 │
│ ┌─ 所有层级 ─────────────────────────┐ │
│ │ ① 问题归因（设计缺陷/偏离/遗漏） │ │
│ │ ② 10星挑战（当前几星→10星差距） │ │
│ └─────────────────────────────────────┘ │
│ ┌─ 标准+深度 ─────────────────────────┐ │
│ │ ③ 模块健康度检查 │ │
│ └─────────────────────────────────────┘ │
│ ┌─ 仅深度 ───────────────────────────┐ │
│ │ ④ 假设审查 ⑤ 反驳机制 │ │
│ └─────────────────────────────────────┘ │
│ → [询问用户] 展示诊断结果，确认方向 │
└───────────────────────────────────────────────┘
│
▼
┌─ 第3步：方案确认 ─────────────────────────────┐
│ 逐项讨论变更点（当前→目标→推荐→可选） │
│ → [多轮询问用户] 每个变更点确认 │
│ → [询问用户] 汇总变更清单，最终确认 │
│ ⚠️ 门禁：确认前不写任何文件 │
└────────────────────────────────────────────────┘
│ 用户确认 ✓
▼
┌─ 第4步：写入文档 ─────────────────────────────┐
│ A. 更新/新建 Feature Spec（.features） │
│ B. 将最终有效结论回写 PRD 当前事实 │
│ C. 更新 CHANGELOG 历史账本 │
│ → 输出最终总结 │
└────────────────────────────────────────────────┘
```
---
## 可视化规范
需要图示辅助判断时（架构图/流程对比/状态机），先读
[references/prd-details.md](references/prd-details.md) 的可视化规范节。
> 提问格式与批量策略见 `~/.claude/skills/_shared/interaction-protocol.md`。
---
## 第0步：定位项目、PRD 与 CHANGELOG
1. 根据用户提供的目录线索，用 Glob 搜索 PRD 文件：
```
搜索模式（按优先级）：
- {项目目录}/docs/PRD.md
- {项目目录}/docs/prd.md
- {项目目录}/docs/*PRD*
- {项目目录}/docs/*需求*
- {项目目录}/PRD.md
- {项目目录}/**/PRD*.md
```
2. 搜索 CHANGELOG 文件（不写死文件名，模式匹配）：
```
搜索模式：
- {项目目录}/docs/*changelog*（不区分大小写）
- {项目目录}/docs/*CHANGELOG*
- {项目目录}/docs/*变更*
- {项目目录}/**/CHANGELOG*
- {项目目录}/**/changelog*
```
3. 分支判断：
- 找到 PRD → 进入「迭代模式」（第1步）
- 找不到 PRD，和用户确认是否进入「创建模式」，用户确认后生成PRD（第1步-替代）
- 找不到 CHANGELOG → 标记需要在第4步新建（基于项目文档 + git history 回溯生成）
---
## 第1步：理解现状（迭代模式）
1. 读取 `docs/README.md`、`docs/INDEX.md` 和 `docs/PRD.md` 当前真相源。
2. 按需读取 `docs/modules/*`、当前代码和相关接口/表。
3. 读取 `docs/CHANGELOG.md` 顶部索引；只有本次问题需要历史原因时，才读取 `PRD-CHANGELOG.md` 的相关段落，不默认扫全文。
4. **CHANGELOG 热点分析**：
- 统计各模块被修改的频次
- 识别「反复修改但未根治」的模块（同一模块在多个版本中出现）
- 如果发现热点模块与用户本次需求相关，主动提示
5. 用 Agent 工具深度分析项目源码：
- 使用 Explore 子代理扫描项目结构、关键文件、技术栈
- 重点关注：当前实现与 PRD 描述的差异、用户描述的问题
6. 向用户总结当前产品状态（3-5句），确认理解是否正确
- 如果项目模块较多（≥4个）或存在热点模块数据，考虑用 widget 渲染指标卡片和热点柱状图
- 简单项目直接文字总结即可
7. 询问用户本次迭代的需求或问题
---
## 第1步（替代）：从零创建 PRD
项目没有 PRD 时走此分支：深度读代码 + 多轮交互确认后生成完整 PRD。
细则必读 [references/prd-details.md](references/prd-details.md)；模板用 [references/prd-template.md](references/prd-template.md)。
## 第2步：诊断与审查（自适应深度）
### 审查深度自动判定
| 层级 | 触发条件 | 做什么 |
|------|----------|--------|
| **轻量审查** | 单个小改动（改阈值、调文案、修参数） | 归因 → 10星挑战 → 确认方案 |
| **标准审查** | 功能调整、多个小改动集中在同一区域 | 归因 + 模块健康度 + 10星挑战 + 方案对比 |
| **深度审查** | 新模块、架构调整、或 CHANGELOG 显示某模块反复修改 | 假设审查 + 10星挑战 + 反驳机制 |
**自动升级规则**：
- 多个小需求集中在同一模块 → 从轻量升级到标准
- CHANGELOG 中某模块在 ≥3 个版本中被修改 → 升级到深度，主动告知用户："这个模块已经在 vX.X、vX.X、vX.X 中反复修改，建议做一次彻底审查"
- 用户主动要求更深度的审查 → 升级
### 诊断流程（所有层级通用）
1. **问题归因**：
- **产品设计缺陷**：PRD 中对该场景的定义就不完整或不合理
- **实现偏离 PRD**：PRD 写得对但代码实现偏离了
- **PRD 遗漏场景**：PRD 根本没考虑到这个场景
- 明确告知用户属于哪种情况
2. **10星挑战**（所有层级必做）：
- 当前方案几星？
- 10星版本是什么样的？
- 差距是"小"（可以做完）还是"大"（超出当前范围）？
- 轻量审查：简要挑战即可（1-2句）
- 标准/深度审查：展开讨论，用并排对比图展示当前 vs 10星方案
3. **模块健康度检查**（标准/深度层级）：
- 该模块在 CHANGELOG 中的修改历史
- 该模块当前实现与 PRD 的一致性
- 是否存在关联模块需要同步调整
### 深度审查额外步骤（借鉴 cn-plan-product）
4. **假设审查**：
- PRD 中对该模块的隐含假设是什么？
- 这些假设是否仍然成立？
- 用户的新需求是否暴露了错误的假设？
5. **反驳机制**：
- 如果认为用户提的需求放在这里不合适，直接说出来
- 给出替代方案或建议砍掉某些不需要的功能
- 从整体产品视角评估，而非只看单个需求点
### 诊断输出
向用户展示：
- 问题归因结果
- 模块健康度评估（如适用）
- 建议的方向：新增功能 / 优化现有功能 / 砍掉不需要的功能 / 调整架构
**可视化判断**：根据诊断复杂度决定是否用 widget：
- 归因路径涉及多个因果环节 → 用 SVG 流程图展示归因链
- 涉及多个模块的健康度评估 → 用 SVG 评分卡矩阵（Emerald=健康，Amber=需关注，Rose=需修复）
- 10 星挑战（标准/深度层级） → 用并排对比图展示当前 vs 10星方案
- 单一明确问题 → 直接文字说明即可
等待用户确认方向后进入第3步。
---
## 第3步：方案确认
通过 AskUserQuestion 逐项讨论每个变更点：
1. **当前行为**：现在是什么样的
2. **目标行为**：期望变成什么样的
3. **推荐方案**：给出推荐并说明理由
4. **可选方案**：列出替代方案（如有），标注完整度
5. **做与不做**：明确确认什么做、什么不做、什么推迟，以及原因
**可视化判断**：
- 单个变更点的讨论 → 文字即可
- 多个可选方案需要对比 → 用 SVG 并排对比图展示各方案优劣
- 变更点涉及复杂的行为差异 → 用「当前 vs 目标」对比图
讨论完成后，汇总变更清单：
- 变更项 ≤3 个 → 文字清单
- 变更项 ≥4 个 → 考虑用交互式 widget 汇总（含类型颜色编码和优先级标注）
通过 AskUserQuestion 请用户最终确认。
**⚠️ 关键门禁：在用户明确确认变更清单之前，不得写入任何文件（CHANGELOG、PRD）。** 第3步的产出仅在对话中展示，不写入磁盘。
---
## 第3.5步：生成 Feature Spec（用户确认门禁）
**门禁不变**：Feature Spec 需用户确认后才可进开发；每个功能点至少 3 种异常态
（空态/错误态/降级态，涉本地存储加陈旧态），异常态的 Then 必须写明确 UI 行为。
**交给用户前先跑四点自审**（Superpowers v5 Spec Self-Review，约 30 秒抓 4-5 个问题）：
1. 占位符扫描——还有 TBD/TODO/含糊需求吗？有就先补
2. 内部一致性——章节之间打架吗？结构和功能描述对得上吗？
3. 范围检查——一个实现计划装得下吗？装不下就拆
4. 歧义检查——哪条需求能读出两种意思？选定一种写死
自审改完再给用户确认；用户要求修改后必须重跑自审。
生成细则必读 [references/prd-details.md](references/prd-details.md)；模板用 [references/feature-spec-template.md](references/feature-spec-template.md)。
## 第3.6步：生成/更新项目 CLAUDE.md
**首次运行时**（项目根目录不存在 CLAUDE.md）：
1. 读取 [references/project-claude-md-template.md](references/project-claude-md-template.md)
2. 填充项目名称、文档路径等变量
3. 写入 `{项目根目录}/CLAUDE.md`
**已有 CLAUDE.md 时**：
1. 读取现有内容
2. 检查是否已包含 `## Forge 工作流` 章节
3. 如果没有，在文件末尾追加 Forge 章节（不覆盖已有内容）
4. 如果已有，跳过（不重复写入）
---
## 第4步：写入文档（用户确认后执行）
**前提：用户已在第3步确认变更清单，且在第3.5步确认 Feature Spec。** 确认后一次性产出并写入以下内容：
### A. 更新 CHANGELOG
在 CHANGELOG 文件中追加本次变更记录（如果 CHANGELOG 不存在，新建并基于 git history 回溯生成历史记录）。
参考格式见 [references/prd-template.md](references/prd-template.md) 的 CHANGELOG 格式部分。
每条变更记录包含：
- **时间戳**：精确到日期
- **变更背景**：为什么要做这次变更
- **用户原始需求**：用户的原话或需求描述
- **设计方案**：采用的方案摘要
- **关键决策表**：议题 / 决定 / 原因
- **影响范围**：新增、修改、删除了什么
### B. 写入 Feature Spec
1. 将第3.5步用户确认的 Feature Spec 写入 `.features/{feature-id}/feature-spec.md`。
2. 更新 `.features/{feature-id}/status.md` 和 `.features/_registry.md`。
3. Feature Spec 必须包含用户流程、页面/系统结构、Given/When/Then、验收清单和非目标。
4. 不把完整 Feature Spec 长期塞进 `docs/PRD.md`。
### C. 更新 PRD 当前事实
1. 只把本轮确认后仍有效的产品事实回写到 `docs/PRD.md`。
2. 新增功能 → 更新对应页面/模块职责、输入/处理/输出、接口/read model 映射。
3. 修改功能 → 原位更新当前规格，不在正文堆版本号和历史过程。
4. 砍掉的功能 → 从当前事实移除，必要时在“非目标/产品债”中保留一句当前边界。
5. 涉及表/API/read model 的变化 → 同步到对应映射和验收方式。
6. 自洽性检查：PRD 当前事实、Feature Spec、CHANGELOG 互不矛盾。
### D. 产出迭代交付说明
在 PRD 的「本次迭代摘要」中包含面向下游 Agent 的交付说明：
- **变更摘要**（3-5行）
- **关键流程变化**（如有流程图则更新）
- **前端变更要点**：涉及哪些页面/组件、交互变化、视觉变化
- **后端变更要点**：涉及哪些 API/数据模型、逻辑变化
- **设计变更要点**：配色/布局/组件样式变化（如适用）
- **测试验收标准**：每个变更点对应的验收条件
- **Agent 补充信息**：
- 受影响的文件路径提示（基于源码分析）
- 数据库迁移注意事项（如涉及 schema 变更）
- 兼容性提醒（如涉及 API 变更对前端的影响）
- 关联变更提示（改 A 可能需要同步改 B）
此部分内容在对话中与用户确认核心方向后，由 skill 补充 Agent 所需的技术细节，一并写入 PRD。
---
写入完成后，输出最终总结：
- 如果本次迭代变更较多（≥4项）或涉及多个模块 → 用 widget 渲染完成仪表盘（指标卡片 + 变更统计图）
- 简单迭代 → 文字总结即可，包含：项目名、版本变更、诊断层级、变更数、文件状态
---
## Feature 状态管理（.features/ 架构）
核心三条：① 每个 feature 一个 `.features/{id}/status.md`，prd 行本 skill 负责更新；
② 全局注册表 `_registry.md` 同步 heartbeat；③ 状态值只用 ⏳/🔄/✅/❌。
字段与操作细则见 [references/prd-details.md](references/prd-details.md)。
## 完整性原则
- PRD 是给后续 agent（设计、开发、QA）看的，必须准确、完整、无歧义
- CHANGELOG 是给人和 agent 看的，需要记录决策上下文和"为什么"
- 宁可多问一个问题，不要假设用户意图
- 每个变更点都要有明确的「当前行为」和「目标行为」对比
- 用户描述的是症状，skill 要做的是诊断——找到根因，而非只处理表面
- 对于带前端的项目，PRD 应覆盖设计系统、配色方案、交互细节
- 对于纯后端项目，PRD 应覆盖 API 设计、数据模型、性能要求
- 如果认为需求不合理，直接反驳并给出替代方案
---
## 资源
- **PRD 模板与 CHANGELOG 格式**：[references/prd-template.md](references/prd-template.md)
- **Feature Spec 模板**：[references/feature-spec-template.md](references/feature-spec-template.md)
- **项目 CLAUDE.md 模板**：[references/project-claude-md-template.md](references/project-claude-md-template.md)