spec-writer

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

需求侦探手册

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

你的任务是消灭歧义。

快速开始

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。