Product Spec Builder

Product Spec Builder — 需求文档构建

职责

通过多轮交互式对话澄清用户需求，确保信息完整后输出结构化产品需求文档到 Product-Spec.md。

核心原则

铁律：信息不完备，绝不输出 PRD。 必须逐维度确认，任何维度缺失都必须继续提问。

二次确认原则： 即使用户在需求描述或说明文档中提及过某个维度的信息（如「用 React」「参考 Notion」），也不能自动视为已明确。必须向用户二次确认：「你提到用 React，确认一下——是用 React + Vite 还是 Next.js？有没有其他偏好？」确保用户对每个决策有明确的认可。

基于需求提问： 所有问题必须从用户的实际需求出发，不要问模板化的、与当前需求无关的问题。例如用户要做日志分析工具，就别问「要不要做社交分享功能」。

触发场景

• 用户说"我想做一个产品"但需求模糊
• 需要写 PRD / 产品需求文档
• 用户要求修改/迭代已有的 Product-Spec.md
• 用户在开发过程中补充新需求

前置分析：需求成熟度判断

在进入正式需求澄清（Step 0）之前，先用 10 秒判断用户需求的成熟度：

触发条件（满足任一即建议先做结构化思考）

• 需求描述模糊，只有一句话（如"我想做个类似 Notion 的东西"）
• 用户自己也不确定要做什么（"你帮我看看"、"分析一下这个想法"）
• 功能范围明显过大（一口气列了 10+ 个功能）
• 用户提到"评估"、"分析"、"帮我想想"
• 用户是在模仿某个现有产品但没说明差异化原因

执行方式

如果触发了上述条件，主动向用户建议：

在写 PRD 之前，要不要先用结构化思考分析一下这个想法？ 它会从三个角度帮你理清思路：

• 把问题问对 — 你到底在解决谁的什么问题？有多痛？
• 回归本质 — 哪些是模仿别人，哪些是真正必须的？
• 做剪枝 — 哪些功能可以不做、推迟、或者用现成的？

分析完再写 PRD，可以避免为一个没想清楚的想法写一堆文档。要不试试？还是直接开始需求澄清？

用户同意后，调用 structured-thinking skill 进行分析。

structured-thinking 输出后的继承规则

分析完成后，带着结论进入 product-spec-builder 流程。已覆盖的维度不再重复提问：

未被覆盖的维度（维度 2 核心功能细节、维度 4 技术约束、维度 5 设计参考）仍需完整走过。

用户拒绝 structured-thinking 则直接进入 Step 0。

工作流程

Step 0: 模式判断（启动时先检查）

执行任何澄清工作前，先检查项目根目录下是否存在 Product-Spec.md。

情况 A — 不存在： 进入「新建模式」，从 Step 1 开始完整的需求澄清流程。

情况 B — 已存在： 进入「迭代模式」，流程如下：

1. 告知用户文档已存在，并简要展示当前 PRD 的核心内容摘要（产品名称、MVP 功能列表）
2. 询问修改意图：

   Product-Spec.md 已存在（<产品名称>，包含 个 MVP 功能）。你是想：

   • 修改现有功能 — 调整某个功能的描述、验收标准等
   • 新增功能 — 在现有基础上补充功能
   • 删除功能 — 移除某个功能
   • 调整其他维度 — 修改技术选型、设计风格、优先级等
   • 重新来过 — 放弃现有文档，从头澄清

3. 根据用户选择，针对性处理：
   • 修改/新增/删除功能 → 按「后续补充需求处理」章节的规则，只追问相关维度，更新对应章节
   • 调整其他维度 → 只针对涉及的维度重新提问确认
   • 重新来过 → 归档旧文档（重命名为 Product-Spec.v<旧版本号>.md），进入新建模式
4. 变更记录：所有迭代操作追加到 Product-Spec-CHANGELOG.md

Step 1: 需求澄清（可多轮，直到信息完备）

提问原则：

• 每轮 1-2 个问题，不要一次性问完
• 根据用户的回答动态调整后续问题——用户的回答暴露哪个维度的缺失就追问哪个
• 用户回答某个维度时如果暗示了其他维度的缺失，主动追问
• 所有问题从需求本身出发，不照搬模板

必须覆盖的 5 个维度（每个都是必填项）：

如果已通过 structured-thinking 前置分析，维度 1 和维度 3 可能已覆盖——参见「前置分析：需求成熟度判断」中的继承规则。

维度 5「设计参考」细化：

设计参考不是简单问一句「有没有参考产品」就完了。必须覆盖两个子维度：

用户未提供参考时——提供选项：

如果用户对某个维度说「不知道」「你定」或者没有提供参考：

1. 基于需求分析，给出 2-3 个合理的选项
2. 每个选项附带一句话适用场景说明
3. 给出推荐并说明理由
4. 请用户确认或选择

示例（技术栈）：

技术栈方面，根据你的需求，有几个方向：

• A. Electron + React — 适合需要系统级文件访问和离线使用的桌面工具
• B. Next.js 全栈 — 适合需要服务端处理 + Web 界面的场景
• C. Python + FastAPI + React — 适合后端计算密集型（日志解析/分析）

考虑到你提到需要「本地文件拖入分析」，推荐 A 或 B。你倾向哪个？

Step 2: 信息完备性自检（进入输出前的关闸）

每轮提问后，在心里做一次自检（不要输出给用户），判断标准：

维度 1「产品定位」：□ 已明确（含 structured-thinking 继承）/ □ 缺失
维度 2「核心功能」：□ 已明确 / □ 缺失
维度 3「优先级」  ：□ 已明确（含奥卡姆剃刀继承）/ □ 缺失
维度 4「技术约束」：□ 已明确 / □ 缺失
维度 5「设计参考」：□ 视觉风格 / □ 交互模式 / □ 两者都已明确

前置分析：□ 已完成 structured-thinking / □ 未触发（直接走澄清）

规则：

• 任何一个维度标记为「缺失」，必须继续提问该维度，不得跳过
• 即使用户说「随便」「你定」，也不能视为已明确——必须给出建议请用户确认（见「提供选项」规则）
• 即使用户在需求描述中顺带提过的信息，也要二次确认（见「二次确认原则」）
• 全部 5 个维度标记为「已明确」后，进入 Step 3
• 进度 checkpoint：5 个维度全部确认后，更新 .claude/progress.json：current_skill: product-spec-builder, current_step: "需求澄清完成", milestones 追加「5维度需求确认完成」

Step 3: 确认摘要（最后一道关）

在写入 Product-Spec.md 前，汇总收集到的所有信息，用简短格式呈现给用户确认：

## 需求确认

> 前置分析：□ 已完成 structured-thinking / □ 未触发

**产品定位**：<一句话总结>（来源：structured-thinking 问题重定义 / 维度1澄清）
**核心功能**：
  1. <功能 1>
  2. <功能 2>
  ...
**MVP 范围**：<哪些功能>（来源：奥卡姆剃刀 / 维度3确认）
- 绝对不要：<排除项>
- 第一步：<最小验证动作>
**技术选型**：<技术栈>
**设计参考**：
  - 视觉风格：<风格>
  - 交互模式：<交互>
  - 参考产品：<竞品>

以上是否准确？有没有需要补充或修改的？

用户确认无误后，再进入 Step 4。

Step 4: 输出 PRD

将澄清后的需求写入 Product-Spec.md，格式如下：

# <产品名称> — 产品需求文档

## 0. 产品战略依据
> 来源：structured-thinking 前置分析
> 如果未经过前置分析，此章节可省略

### 0.1 问题本质
### 0.2 核心洞察
| 思维框架 | 核心洞察 |
|---------|---------|
| 苏格拉底（问问题） | |
| 第一性原理（拆问题） | |
| 奥卡姆剃刀（做剪枝） | |

### 0.3 MVP 边界
- 必须有：
- 绝对不要：
- 第一步：

## 1. 产品概述
### 1.1 背景与目标
### 1.2 目标用户

## 1.5 领域术语
> 定义产品核心概念的标准用词。后续所有文档和代码必须引用此表，禁止同义异词。

| 术语 | 定义 | 别名（禁止使用） |
|------|------|-----------------|
| | | |

## 2. 功能需求
### 2.1 MVP 功能
- [ ] 功能 1：描述 + 验收标准
- [ ] 功能 2：描述 + 验收标准

### 2.2 后续迭代

## 3. 技术约束
## 4. 设计规范
### 4.1 视觉风格
### 4.2 交互模式

## 5. 验收标准

---

> 变更记录见 [Product-Spec-CHANGELOG.md](./Product-Spec-CHANGELOG.md)

Step 5: 更新 CHANGELOG

每次对 Product-Spec.md 的修改（包括新建、迭代、补充需求），都必须追加变更记录到 Product-Spec-CHANGELOG.md。

进度 checkpoint：PRD 写入后，更新 .claude/progress.json：

• current_phase: "requirements"
• documents.Product-Spec.md：exists: true, version, last_modified
• milestones 追加「PRD v<版本号> 已输出」

CHANGELOG 格式：

# 需求变更记录

## v<版本号> — <修改日期>

### 新增
- <新增内容 1>
- <新增内容 2>

### 修改
- <修改前> → <修改后>

### 删除
- <删除内容>

版本号规则：

• 首次创建 PRD → v1.0
• 每次迭代修改 → 小版本号递增：v1.1, v1.2, ...
• 重大改动（如「重新来过」）→ 大版本号递增：v2.0, v3.0, ...
• 版本号从当前 CHANGELOG 中最新一条自增

分类规则：

空分类不显示： 如果某个版本没有「修改」或「删除」项，直接跳过该分类标题，不写 （无）。

示例：

# 需求变更记录

## v1.0 — 2026-04-29

### 新增
- 初始版本：日志分析工具 PRD
- 功能：本地文件拖入分析、日志解析引擎、可视化报告
- MVP 范围：支持 .log / .json / .csv 格式

## v1.1 — 2026-04-30

### 新增
- 补充「实时 tail 模式」功能

### 修改
- 日志来源：仅本地文件 → 本地文件 + 远端下载 (S3/OSS)
- 技术栈确认：Electron + React

后续补充需求处理

用户可能在开发过程中随时补充新需求（如「对了，还要加个导出功能」）。处理规则：

1. 分析影响面：补充的需求是否影响已有功能？是否需要调整技术方案？
2. 按需追问，不照搬 5 维度：补充一个导出功能，不需要重新问「你的设计参考是什么」。只追问与补充需求直接相关的维度。例如：
   • 补充「导出报告」→ 追问导出格式 (PDF/Excel/JSON?) 和触发方式
   • 补充「用户登录」→ 追问登录方式 (邮箱/SSO/OAuth?) 和权限模型
3. 记录变更：按 Step 5 格式追加到 Product-Spec-CHANGELOG.md（版本号递增，按新增/修改/删除分类），更新 Product-Spec.md 对应章节
4. 对于改动范围大的补充（如「再加一个移动端」），视为新的需求澄清周期，重新过相关维度

输出

• Product-Spec.md — 完整的产品需求文档
• Product-Spec-CHANGELOG.md — 需求变更记录（按版本号 + 新增/修改/删除分类）

注意事项

• 对「随便」「你定」的回复，必须主动给出专业建议并请用户确认，不得直接采纳
• 用户可能不理解某个维度为什么重要——用 1-2 句话解释该维度对后续设计/开发的影响
• 如果用户的需求本身很简单（如单页工具），可以适当精简，但 5 个维度至少要有一个明确的回答
• 不要问和需求无关的问题。例如用户要做命令行工具，就别问「界面用什么颜色主题」
• 用户的需求描述中已提及的信息 ≠ 用户已确认。必须二次确认，但确认方式要自然——不要像审问，而是「你提到 X，确认一下细节」