# Product Spec Builder

> 需求收集与问题澄清。新建或迭代 PRD，通过交互式澄清生成结构化产品需求文档。

- Skill: `herxinsasa/product-spec-builder` (Agent Skill)
- Install (CLI): `npx skillmds@latest add herxinsasa/product-spec-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/herxinsasa/product-spec-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: herxinsasa (https://skillmd.com/u/herxinsasa)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/herxinsasa/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 流程。**已覆盖的维度不再重复提问：**

| structured-thinking 输出 | 映射到 product-spec-builder | 处理方式 |
|--------------------------|---------------------------|---------|
| 苏格拉底：问题重定义、关键矛盾 | 维度 1「产品定位」 | **跳过**，直接引用作为产品定位 |
| 第一性原理：本质拆解、类比陷阱 | 维度 0「产品战略依据」（新增） | 追加到 PRD 作为战略上下文 |
| 奥卡姆剃刀：MVP 边界、可删除项 | 维度 3「优先级」 | MVP 范围已有，**只确认不重问** |
| 综合结论：建议方案、定位、第一步 | 维度 1 + 维度 3 | **直接引用**，确认即可 |

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

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

---

## 工作流程

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

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

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

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

1. **告知用户文档已存在**，并简要展示当前 PRD 的核心内容摘要（产品名称、MVP 功能列表）
2. **询问修改意图**：
   > Product-Spec.md 已存在（<产品名称>，包含 <N> 个 MVP 功能）。你是想：
   > - **修改现有功能** — 调整某个功能的描述、验收标准等
   > - **新增功能** — 在现有基础上补充功能
   > - **删除功能** — 移除某个功能
   > - **调整其他维度** — 修改技术选型、设计风格、优先级等
   > - **重新来过** — 放弃现有文档，从头澄清
3. **根据用户选择，针对性处理**：
   - **修改/新增/删除功能** → 按「后续补充需求处理」章节的规则，只追问相关维度，更新对应章节
   - **调整其他维度** → 只针对涉及的维度重新提问确认
   - **重新来过** → 归档旧文档（重命名为 `Product-Spec.v<旧版本号>.md`），进入新建模式
4. **变更记录**：所有迭代操作追加到 `Product-Spec-CHANGELOG.md`

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

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

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

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

| # | 维度 | 必须明确的内容 | 完备判定标准 | 前置分析状态 |
|---|------|---------------|-------------|-------------|
| 1 | **产品定位** | 产品名称、解决什么问题、目标用户画像 | 能用一句话说清「谁、遇到什么问题、我们的解决方案」 | ⚠️ structured-thinking 已覆盖则跳过 |
| 2 | **核心功能** | 3-5 个核心功能，每个功能的输入/输出/流程 | 每个功能有清晰的用户故事和使用场景 | 必须完整走过 |
| 3 | **优先级** | MVP 范围 vs 后续迭代、功能依赖关系 | MVP 功能列表已锁定，不含模糊项 | ⚠️ 奥卡姆剃刀已给出边界，只确认不重问 |
| 4 | **技术约束** | 平台 (Web/移动/桌面)、技术栈偏好、部署方式 | 能确定项目初始化的技术选型 | 必须完整走过 |
| 5 | **设计参考** | 竞品/参考产品、设计风格、交互模式 | 能描述目标产品的视觉走向和核心交互方式 | 必须完整走过 |

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

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

| 子维度 | 说明 | 示例问题 |
|--------|------|---------|
| **视觉风格** | 配色、布局、组件风格 | 「偏好 Material Design 还是极简风格？喜欢暗色还是亮色主题？」 |
| **交互模式** | 核心操作的交互流程、导航结构 | 「日志导入是拖拽上传还是选择文件？结果是实时刷新还是手动触发分析？」 |

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

如果用户对某个维度说「不知道」「你定」或者没有提供参考：
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`，格式如下：

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

## 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 格式：**

```markdown
# 需求变更记录

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

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

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

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

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

**分类规则：**

| 操作 | CHANGELOG 分类 | 示例写法 |
|------|---------------|---------|
| 补充新功能、新需求 | **新增** | `新增「导出PDF报告」功能` |
| 调整现有功能的描述/验收标准/范围 | **修改** | `「拖入分析」支持范围改为：支持单/多文件拖入` |
| 调整技术选型、设计风格等非功能维度 | **修改** | `技术栈：Electron → Next.js` |
| 删除功能或需求 | **删除** | `删除「社交分享」功能` |

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

**示例：**

```markdown
# 需求变更记录

## 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，确认一下细节」