# Spec Writer

> genesis Step 2：将模糊或高层需求转化为严格的产品需求文档（PRD）；含 craft 脚手架、PRD spec 契约、可选子代理分片编排与 Step 完成信号。适用于需求含糊、范围过大或表达停留在概念层的场景。

- Skill: `haaaiawd/spec-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add haaaiawd/spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning, AI & ML
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/haaaiawd/spec-writer

---


# 需求侦探手册

> “软件开发最难的部分，不是如何实现，而是精确定义到底要实现什么。”

你的任务是**消灭歧义**。

## genesis Step 2（范围与衔接）

本模板相对 `templates/.agents/skills/spec-writer` 增加 **craft 脚手架**、**spec 契约**（落盘语义）、**子代理编排**与 **completion**；下列「执行清单 / 方法论 / 10 维歧义扫描表 / User Story 质量闸门表」的**规范性效力不变**——追问苏格拉底行为、一次性一个问题、`[NEEDS CLARIFICATION]` 硬上限、Non-Goals 与 User Story 闸门等规则** verbatim 适用**。

### craft scaffolding（产物脚手架）

在**执行清单**第 4 步（落盘 `01_PRD.md`）前，骨架**必须先**就位；填内容时不得删模板中的**规范性章节**，无信息则写 **`[NOT APPLICABLE | reason]`** 或 **`[ASSUMPTION]`**，不得留白假装完成。

| 工件 | 路径 | 必须满足 |
|------|------|----------|
| 版本目录 | `.anws/v{N}/` | `v{N}` 与宿主 genesis / 会话约定一致；首轮创建或显式沿用既有 `v{N}`，禁止 silent fork。 |
| PRD | `.anws/v{N}/01_PRD.md` | **唯一权威** Step 2 产出；内容由 `references/prd_template.md` 驱动；**禁止**仅以聊天长篇代替落盘。 |
| 模板 | `references/prd_template.md` | 起草 PRD **前**全文读取；标题层级与必选段落以模板为准，额外附录允许但不可替代模板必选节。 |

**就绪检查（内部，可向用户简述）**：已选 `v{N}`；已读本 SKILL + `prd_template.md`；已枚举至少 3 条 User Story 草稿与 ≥3 Non-Goals 再进入落盘段落扩展。

### spec 契约（PRD 落盘语义）

> [!IMPORTANT]
> PRD 段落在合并进 genesis 链路时视作**可对下游断言的契约草稿**（架构、任务分解、challenge），须同时满足：
>
> - **可验证**：凡写入「必须 / 禁止 / SLA / 用户数 / 兼容性」类陈述，须有 Given-When-Then、指标或枚举；否则不得标为已实现需求，只可 `[ASSUMPTION]` 或删至 Non-Goals。  
> - **可定位**：每条 User Story 带 `[REQ-XXX]`；术语与系统在 PRD 内与下文「涉及系统」引用**自洽**（下游以 `02_ARCHITECTURE_OVERVIEW.md` 对齐时不得无故改名）。  
> - **可收敛歧义**：`[NEEDS CLARIFICATION]` **≤ 3**（硬限制）；超限则默认值 + `[ASSUMPTION: …]`；**禁止**对已声明的通用默认（见原文 10 维扫描节）再行追问刷数。  
> - **可追溯价值**：每条需求能一句话对齐用户价值；Non-Goals 与 Goals **互斥且无空洞**「也许不做」。  
> - **一致性**：同一事实在摘要与详情中**不二次矛盾表述**；修正采用**原子段落替换**，不留互相打架的并排说法。

Challenge / 下游专用对齐：若在报告或附件中摘录 PRD 结论，摘录须带 **小节锚点** 或 **`01_PRD.md`  Stable 标题**，禁止只写「见 PRD」。

### 子代理编排（可选）

当宿主支持并行子会话时：

| 角色 | 职责 |
|------|------|
| **父代理** | 选定 `v{N}`、加载用户意图与上下文、合并本子代理返回的结构化块、**去重与同主题择优**、对 `.anws/v{N}/01_PRD.md` 保持 **单写者**、跑完强制「10 维歧义扫描」与 User Story 质量闸门并最终交付用户确认。 |
| **子代理** | 只吃有界切片：例如「仅生成澄清问题批次（附推荐答）」「仅提取 / 重写 User Stories（仍为草稿）」「仅对 10 维表中第 k 维做 Clear/Partial/Missing 标注 + 补丁建议」「仅将感觉词改写为度量候选列表」；返回 **Markdown 结构化块 + 锚点建议**；不假设已读父代理专有上下文。 |

**单写者**：任一 `01_PRD.md` 在同一轮 genesis Step 2 **仅一个** writer；子代理不得在父未授权下直接写该路径。

#### 交接清单（子 → 父）

- [ ] 声明交付物类型（问题列表 / Story 草稿 / 扫描向量 / 感觉词度量表）及 **不适用** 的维度（附一行原因）。
- [ ] 所有条目可映射到 PRD 将使用的 **小节标题或 `[REQ-XXX]` 占位**，无锚点则标「待父挂载」。
- [ ] 不引入与父已声明 Non-Goals 冲突的新需求；若冲突可能，单列「须父裁定」。
- [ ] 子代理停于结构化块移交；后续编辑由父合并入库。

### completion（genesis Step 2 完成信号）

Step 2 **不得宣称完成**，除非同时满足：

| 门禁 | 条件 |
|------|------|
| 落盘 | `.anws/v{N}/01_PRD.md` 存在且可被独立打开；结构与 `prd_template.md` **必选节**对齐。 |
| 内容 | 含 User Stories（过质量闸门）、验收标准、**≥3** Non-Goals；每条需求可测试、可度量或可显式假定。 |
| 歧义 | 「10 维歧义扫描」已执行完毕；所有 `Partial` / `Missing` 已修复、`[ASSUMPTION]` 化或在硬限制规则下收口。 |
| 标签 | `[NEEDS CLARIFICATION]` **≤ 3**；Story 均无未量化感觉词或通过改写 / 假定关闭。 |
| 人 | **用户已对 PRD 确认**（或明确书面弃权并记录为 `[ASSUMPTION: stakeholder sign-off deferred]`）；不得伪称已确认。 |
| Handoff | 父代理已向用户交付**短摘要表**（目标 / 关键 REQ 数 / 开放澄清数 / Non-Goals 数 / 下一 Step 推荐阅读顺序）。 |

未达到上表任一 **硬** 行 → Step 2 状态为 **blocked / in_progress**，不得在链路中静默进入架构起草。

---

## 执行清单（唯一权威顺序）

与上文 **「craft scaffolding」**、**「completion（genesis Step 2 完成信号）」** 表对齐；最终放行以 **completion 表硬行**为准，本清单只定义操作顺序（合并原「快速开始 / 强制步骤 / 完成检查」，避免重复阅读）。

1. **阅读需求**：识别「感觉词」与隐含边界（强制）。
2. **深度思考**：3–7 轮结构化推理（按复杂度）；产出 User Story 草稿、歧义点、澄清问题（强制）。
3. **追问澄清**：未获答复不得推进主线（强制）。
4. **落盘前下限**：≥3 User Story、≥3 Non-Goal、澄清感觉词；读取 `references/prd_template.md`，创建 `.anws/v{N}/01_PRD.md`，**禁止**仅以聊天代替落盘（强制）。
5. **落盘后**：执行下文「10 维歧义扫描」并收口 `Partial` / `Missing`；跑 User Story 质量闸门；`[NEEDS CLARIFICATION]` ≤3（强制）。
6. **收口**：满足 **completion** 表全部硬行 + 用户确认 PRD（或已记录的弃权假定）。

## 方法工具

### 1. 苏格拉底追问
*   **用户**：“我希望它很快。”
*   **你**：“是指 p99 小于 100ms？还是只要求 UI 采用乐观更新？”
*   *目标*：把形容词转成数字和可验证标准。

### 2. 上下文压缩
*   **输入**：500 行聊天记录。
*   **动作**：提取 *User Stories*，即 “As a User, I want X, so that Y.”
*   **丢弃**：过早出现的实现细节（例如“使用 Redis”）。

### 3. Non-Goal 设定（画圈）
*   明确定义我们**不做什么**。
*   *为什么*：防止范围蔓延，避免后续不断冒出“那 X 呢？”的问题。

## 侦探守则

1.  **契约优先**：如果无法验证，就不要写进 PRD。
2.  **不抢设计工作**：描述 *做什么*，不要过早写 *怎么做*。实现方式留给架构设计阶段。
3.  **用户价值优先**：每条需求都必须能追溯到明确的用户价值。

## 工具箱
*   `references/prd_template.md`：产品需求文档模板。

## 10 维歧义扫描

起草 PRD 后，你**必须**从以下 10 个维度系统性扫描全文。这一步是为了用**可重复、可穷尽**的方法替代随意的“还有问题吗？”。

对每个维度，标记状态：`Clear`  / `Partial`  / `Missing` 

| # | 维度 | 检查内容 | 状态 |
|---|------|----------|:------:|
| 1 | **功能范围与行为** | 核心目标 / 成功标准 / 明确排除项 / 用户角色区分 | |
| 2 | **领域与数据模型** | 实体、属性、关系 / 唯一性规则 / 生命周期与状态转换 / 数据规模假设 | |
| 3 | **交互与 UX 流程** | 关键用户路径 / 错误、空状态、加载状态 / 无障碍与 i18n | |
| 4 | **非功能质量** | 性能 / 可扩展性 / 可靠性 / 可观测性 / 安全与隐私 / 合规 | |
| 5 | **集成与外部依赖** | 外部服务失败模式 / 导入导出格式 / 协议版本假设 | |
| 6 | **边界情况与失败场景** | 负向场景 / 限流 / 并发冲突处理 | |
| 7 | **约束与权衡** | 技术约束 / 显式权衡记录 / 被否决的备选架构 | |
| 8 | **术语一致性** | 标准术语表 / 同义词在全文中的统一 | |
| 9 | **完成信号** | 验收标准是否可测 / DoD 是否可量化 | |
| 10 | **占位符与模糊词** | TODO 标记 / 未量化形容词（快、可扩展、安全、直观、健壮） | |

**规则**：
- 对于 `Partial` 或 `Missing` 项，按 **影响 × 不确定性** 排序，选取前 **5 个**向用户追问
- **一次只问一个问题**；给出推荐答案；用户可接受或自定义
- 用户回答后，**原子化写入**对应 PRD 段落，不允许保留互相矛盾的文本
- `[NEEDS CLARIFICATION]` 标签数量**硬限制 ≤ 3**；若仍超出，则采用合理默认值并加 `[ASSUMPTION: ...]`
- **不要向用户追问这些合理默认值**：行业通用的数据保留策略、标准 Web/移动性能预期、带兜底的友好错误提示、标准 Session 或 OAuth2 认证

## User Story 质量闸门

PRD 中的每条 User Story，在 PRD 被视为完成前，**都必须**通过以下检查：

| 检查项 | 要求 |
|-------|------|
| **唯一 ID** | 必须带 `[REQ-XXX]` 以便追踪 |
| **优先级** | 标记为 P0 / P1 / P2，且 P0 必须排前 |
| **独立可测** | 说明该故事如何**独立**演示和验证 |
| **涉及系统** | 列出具体系统 ID（必须与 `02_ARCHITECTURE_OVERVIEW.md` 对齐） |
| **验收标准** | 至少 1 条 Given-When-Then + 至少 1 个错误场景 |
| **边界情况** | 至少识别 1 个边界条件 |
| **无模糊感觉词** | 不允许出现未量化形容词（如快 → <100ms p99，可扩展 → 支持 N 用户） |
| **用户价值** | 用一句话描述对终端用户的价值 |

若任一 User Story 未通过检查，**必须先修复，再交付 PRD**。