# Spec Writer

> 将模糊或高层需求转化为严格的产品需求文档（PRD）。适用于需求含糊、范围过大或表达停留在概念层的场景。

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

---


# 需求侦探手册

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

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

## 快速开始

1.  **阅读需求（强制）**：阅读用户请求与上下文，识别其中的“感觉词”（如“快”“现代”“简单”）。
2.  **深度思考（关键）**：你**必须**进行 3-7 轮结构化推理（视复杂度而定），完成以下工作：
    *   提取 User Story（As a X, I want Y, so that Z）
    *   识别歧义点
    *   起草澄清问题
3.  **追问澄清**：向用户提出问题。**未获得答案前不得继续**。
4.  **起草 PRD（强制）**：读取 `references/prd_template.md`，然后创建 `.anws/v{N}/01_PRD.md`。
5.  **歧义扫描（强制）**：起草完成后，执行下文的“10 维歧义扫描”。对发现的问题就地修正，或标记为 `[ASSUMPTION]`。
6.  **User Story 质量闸门（强制）**：验证每条 User Story 都通过下文质量检查表。

## 强制步骤
在创建 PRD 之前，你**必须**：
1. 提取至少 3 条清晰的 User Story。
2. 定义至少 3 条 Non-Goal（明确**不做什么**）。
3. 向用户澄清“感觉词”（例如：“快”具体意味着什么？“现代”指什么？）。
4. 创建输出文件，**不要只在聊天里打印内容**。

在创建 PRD 之后，你**必须**：
5. 执行“10 维歧义扫描”，修复或标记所有 `Partial` / `Missing` 项。
6. 验证每条 User Story 都具备：优先级 / 独立可测 / 涉及系统 / 边界情况。
7. 确保 `[NEEDS CLARIFICATION]` 标签数量 ≤ 3（硬限制）。若超出，则采用合理默认值并加 `[ASSUMPTION]` 标签。

## 完成检查清单
- [ ] PRD 文件已创建：`.anws/v{N}/01_PRD.md`
- [ ] 包含 User Stories、验收标准、Non-Goals
- [ ] 每条需求都可测试、可度量
- [ ] 用户已确认 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**。