product-spec-builder

通过分阶段需求访谈创建或更新 Product-Spec.md,在设计、DEV-PLAN 或 coding 前澄清需求。用于新产品、功能、MVP、应用、工作流、自动化、AI agents 或较大的软件变更;不用于 bug fixing、code review、release work,或规格已接受后的 implementation planning。

SKILL.md

GitHub

产品规格构建器

通过聚焦的多轮需求发现,把模糊的产品或功能请求转化为可供开发使用的 Product-Spec.md。

本 skill 的任务是让后续设计、计划、实现、测试和评审不必靠猜。保持通用性。除非用户或当前项目明确需要,不要添加特定领域需求。

预检

提问之前:

  1. 判断请求模式:
    • new-spec:新产品、功能、MVP、工作流或自动化。
    • spec-update:需要修改已有 Product-Spec.md。
    • dev-change:开发已开始,需求可能需要修订。
    • not-spec:用户在请求编码、调试、评审、发布或实现计划。
  2. 如果工作区相关,检查 AGENTS.md、Product-Spec.md、Product-Spec-CHANGELOG.md、DEV-PLAN.md 和 Design-Brief.md。
  3. 依赖引用文件前,先确认文件存在:
    • 起草最终输出时必读:references/product-spec-template.md
    • 访谈时有用:references/stage-gates.md、references/discovery-question-bank.md
    • 需要研究时可选:references/research-policy.md
  4. 如果引用文件缺失,简短说明,并使用本文件里的备用规则。不要假装已经读过缺失的引用文件。
  5. 在用户要求写入文件或确认最终定稿之前,不要创建或覆盖 Product-Spec.md。

模式路由

新规格

执行分阶段需求发现。先明确问题、用户、范围和成功标准,再询问详细 UI、数据模型或实现细节。

规格更新

阅读已有 Product-Spec.md。识别受影响章节和需求 ID。只询问本次变更所必需的问题。尽可能保留稳定 ID。如果存在 Product-Spec-CHANGELOG.md,在规格变更后更新它。

开发中变更

如存在,阅读 Product-Spec.md 和 DEV-PLAN.md。把请求归类为澄清、新需求、替换、范围外请求或实现缺陷。说明它对设计、计划、代码、测试和发布的下游影响。先更新需求;建议后续同步其他文档,不要静默编辑其他文档。

非规格请求

如果请求是编码、调试、代码评审、发布或实现计划,除非缺失需求正在阻塞该工作,否则不要继续使用本 skill。

需求发现规则

  • 把用户视为决策负责人。提问、总结并给出建议;不要静默决定产品范围、MVP 取舍、目标用户、定价、合规姿态或技术约束。
  • 每轮最多问 5 个问题。用户已经提供丰富上下文时,优先问 2-4 个。
  • 把模糊形容词转化为可观察行为、约束或验收标准。
  • 区分产品需求和实现想法。记录必要技术约束,但不要发明架构。
  • 在问题、目标用户、范围、主工作流和验收信号清楚之前,不要进入深层实现细节。
  • 每一轮之后,展示一个紧凑的可见台账和下一组问题。
  • 需求发现达到 3 轮后,提供阶段性规格摘要。达到 5 轮后,建议带着假设定稿、延后低风险事项,或产出草稿。

阻塞级别

对每个开放问题分类:

  • P0 Blocking:没有这个决策,最终规格不能被接受。例如:目标用户、MVP 边界、核心工作流、数据归属、敏感数据姿态。
  • P1 Assumption:只有在假设被明确写出并被接受时,工作才能继续。
  • P2 Deferred:可以稍后安全决策;记录负责人和下游影响。

只有 P0 项会阻塞定稿。只要假设和延后决策已记录,不要因为 P1 或 P2 项阻塞最终规格。

如果用户经过两次尝试仍无法决策,提供 2-3 个带取舍说明的选项,并推荐一个。如果仍未决,在安全时标记为 P1 Assumption 或 P2 Deferred。

可见需求台账

每轮需求发现后,更新这个紧凑台账:

当前模式:
当前关卡:
关卡状态:通过 / 未通过

### 已知
- ...

### 假设
- A-001: ... 来源:Assumption / User Decision / Research-Supported

### 阻塞问题
- BQ-001: ... 级别:P0 / P1 / P2

### 延后事项
- D-001: ... 负责人:... 影响:...

### 范围外
- OOS-001: ...

保持台账简洁;它是控制面,不是最终规格。

来源标记

重要主张和需求使用以下标记:

  • User Decision:用户明确说出或确认的决定。
  • User Provided Fact:用户提供的事实,但不一定是决策。
  • Research-Supported:有引用的外部来源支持。
  • Assumption:agent 提出的、尚未确认的假设。
  • Deferred:用户有意延后的事项。

不要把假设表述成用户决策。

条件性研究

只有研究会改变需求时才做研究。以下情况阅读 references/research-policy.md:

  • 产品参与已有公开市场竞争;
  • 用户要求竞品或可行性分析;
  • 定价、平台政策、合规或快速变化的能力会影响范围;
  • 用户缺少足够上下文来定义差异化。

不要为小型内部工具、代码库局部功能变更、缺陷修复,或用户已经决定产品方向的情况做研究。

敏感数据关卡

如果产品处理个人数据、支付、健康数据、未成年人、私信、上传文件、用户生成媒体、位置数据、公司机密数据、凭据,或会影响外部系统的自动化操作,则隐私/安全问题在解决或被用户明确延后前都是 P0。

覆盖以下内容:收集什么、存储在哪里、谁能访问、保留/删除/导出规则、第三方处理方、日志规则,以及高风险操作是否需要人工批准。

就绪检查清单

当满足以下条件时,规格可以定稿:

  • 产品目标和成功标准明确;
  • 目标用户和角色明确;
  • MVP 范围、非目标和范围外事项明确;
  • 主工作流包含开始状态、用户动作、系统行为、结束状态和主要替代路径;
  • 功能需求可测试并已编号;
  • 数据、集成、平台和约束足够清楚,可用于计划;
  • 重要边界情况和失败处理已列出;
  • 非功能需求已明确、已假设或已延后;
  • 验收标准可观察;
  • P0 问题已解决;
  • P1 假设和 P2 延后决策已记录。

输出模式

草稿规格

当用户在就绪前要求文档,或仍有 P0/P1 问题时使用。

草稿输出必须包含 Status: Draft、阻塞问题、假设、延后决策和简短就绪说明。

最终规格

仅当 P0 阻塞项已解决,且用户确认规格可进入下游工作时使用。

起草最终规格前,如可用,阅读 references/product-spec-template.md。如果不可用,使用备用结构:摘要、问题、用户、范围、工作流、需求、数据、界面/集成、边界情况、非功能需求、验收标准、可追踪性、假设、延后决策和交接说明。

文件更新策略

在可写项目内工作时:

  1. 如果不存在 Product-Spec.md 且用户确认定稿,则创建它。
  2. 如果存在 Product-Spec.md,除非用户要求重写,否则增量更新。
  3. 尽可能保留已有稳定需求 ID。
  4. 新 ID 按顺序追加。
  5. 除非用户批准清理,否则不要重编号已有 ID。
  6. 如果存在 Product-Spec-CHANGELOG.md,追加带日期的变更记录。
  7. 如果工作区不应被修改,用一个 markdown 代码块输出完整规格。

输出后,总结已创建/更新路径、捕获的主要决策、延后决策和建议的下一步。

交接

规格被接受后,建议:

  • 如果需要定义 UX、视觉语言或产品交互设计,使用 design-brief-builder。
  • 如果功能已经适合进入实现计划,使用 dev-planner。
  • 如果可行性、集成、平台或合规风险仍未解决,安排技术 spike。