product-spec-builder
通过分阶段需求访谈创建或更新 Product-Spec.md,在设计、DEV-PLAN 或 coding 前澄清需求。用于新产品、功能、MVP、应用、工作流、自动化、AI agents 或较大的软件变更;不用于 bug fixing、code review、release work,或规格已接受后的 implementation planning。
SKILL.md.agents/skills/product-spec-builder/SKILL.md
GitHub产品规格构建器
通过聚焦的多轮需求发现,把模糊的产品或功能请求转化为可供开发使用的 Product-Spec.md。
本 skill 的任务是让后续设计、计划、实现、测试和评审不必靠猜。保持通用性。除非用户或当前项目明确需要,不要添加特定领域需求。
预检
提问之前:
- 判断请求模式:
new-spec:新产品、功能、MVP、工作流或自动化。spec-update:需要修改已有Product-Spec.md。dev-change:开发已开始,需求可能需要修订。not-spec:用户在请求编码、调试、评审、发布或实现计划。
- 如果工作区相关,检查
AGENTS.md、Product-Spec.md、Product-Spec-CHANGELOG.md、DEV-PLAN.md和Design-Brief.md。 - 依赖引用文件前,先确认文件存在:
- 起草最终输出时必读:
references/product-spec-template.md - 访谈时有用:
references/stage-gates.md、references/discovery-question-bank.md - 需要研究时可选:
references/research-policy.md
- 起草最终输出时必读:
- 如果引用文件缺失,简短说明,并使用本文件里的备用规则。不要假装已经读过缺失的引用文件。
- 在用户要求写入文件或确认最终定稿之前,不要创建或覆盖
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。如果不可用,使用备用结构:摘要、问题、用户、范围、工作流、需求、数据、界面/集成、边界情况、非功能需求、验收标准、可追踪性、假设、延后决策和交接说明。
文件更新策略
在可写项目内工作时:
- 如果不存在
Product-Spec.md且用户确认定稿,则创建它。 - 如果存在
Product-Spec.md,除非用户要求重写,否则增量更新。 - 尽可能保留已有稳定需求 ID。
- 新 ID 按顺序追加。
- 除非用户批准清理,否则不要重编号已有 ID。
- 如果存在
Product-Spec-CHANGELOG.md,追加带日期的变更记录。 - 如果工作区不应被修改,用一个 markdown 代码块输出完整规格。
输出后,总结已创建/更新路径、捕获的主要决策、延后决策和建议的下一步。
交接
规格被接受后,建议:
- 如果需要定义 UX、视觉语言或产品交互设计,使用
design-brief-builder。 - 如果功能已经适合进入实现计划,使用
dev-planner。 - 如果可行性、集成、平台或合规风险仍未解决,安排技术 spike。