vibeflow-requirements

name	vibeflow-requirements
description	SRS 文档不存在且无设计文档时使用 — 通过结构化追问产出高质量需求规格说明书，对齐 ISO/IEC/IEEE 29148

需求获取与 SRS 生成

将原始想法转化为结构化、高质量的软件需求规格说明书 (SRS)，通过系统化的获取、质疑和验证流程 — 对齐 ISO/IEC/IEEE 29148 和 EARS 需求语法。

在你展示 SRS 并获得用户批准之前，不得调用任何设计技能、实现技能、编写任何代码、搭建任何项目，也不得采取任何设计/实现行动。无论项目多简单，此规则适用于每个项目。

反模式："这个项目太简单，不需要 SRS"

每个项目都需要经过此流程。一个待办列表、一个单函数工具、一个配置变更 — 全部如此。"简单"项目恰恰是未经审查的假设造成最多浪费的地方。SRS 可以很短（真正简单的项目几句话即可），但你必须展示它并获得批准。

检查清单

你必须按顺序完成以下步骤：

1. 探索项目上下文 — 阅读已有文档、代码、约束；检测 SRS 模板
2. 结构化获取 — 分轮提问，逐一质疑每个需求
3. 分类需求 — 功能 / 非功能 / 约束 / 假设 / 接口 / 排除项
4. 编写需求 — 应用 EARS 模板，分配 ID，编写验收标准
5. 验证 SRS — 检查 8 项质量属性，检测反模式，验证可测试性
6. 展示并审批 SRS — 非简单项目逐节审批
7. 保存需求文档 — docs/changes/<change-id>/requirements.md 并提交
8. 过渡到设计 — 调用 vibeflow-design（含 UCD 内联，如需）

终止状态是进入 vibeflow-design。 不要调用其他阶段。

步骤 1：探索上下文

1. 通读用户提供的需求文档 / 想法描述
2. 运行 python scripts/get-vibeflow-paths.py --json，读取 docs/changes/<change-id>/brief.md 获取问题定义和边界
3. 阅读 .vibeflow/workflow.yaml 了解所选模板的严格度级别
4. 如是现有项目改动，先运行 python scripts/map-change-impact.py --project-root . --source requirements，读取：
   • docs/overview/CURRENT-STATE.md
5. 探索已有代码 / 项目将要构建或集成的仓库
6. 识别初始约束：技术栈、平台、集成、法规
7. 检查 SRS 模板：
   • 如用户指定了模板路径 -> 读取并验证
   • 否则 -> 检查 docs/templates/srs-template.md
   • 验证：模板必须是 .md 文件且至少包含一个 ## 标题

步骤 2：结构化获取

使用 AskUserQuestion 以分轮多问题方式获取需求 — 每轮涵盖一个主题领域，最多 4 个相关问题。对每个领域遵循 捕获 -> 质疑 -> 澄清 循环。

提问方式：

• 按主题分批 — 每轮 2-4 个相关问题合并为一次 AskUserQuestion 调用
• 优先多选 — 每个问题提供 2-4 个选项以降低认知负担
• 假设并确认 — 陈述你的假设，让用户纠正
• 基于场景的边界探索 — "当 [X] 失败时应该怎样？"
• 立即量化 — 在问题本身中用数字替换模糊用词
• 轮内追问 — 如果第 N 轮的回答暴露歧义，在第 N+1 轮处理后再进入下一主题

获取轮次（根据项目上下文调整顺序和分组）：

轮次 1：目的与范围

单次 AskUserQuestion 调用（最多 4 个问题）：

• 该系统解决的核心问题是什么？
• 主要用户是谁？（角色、技术水平）
• 该版本明确排除什么？
• 目标发布范围？（MVP vs 完整版）

轮次 2-N：功能需求

对每个能力域，每轮问（最多 4 个问题）：

• 用户做什么？（触发/动作）
• 系统如何响应？（可观测行为）
• 错误 / 边界 / 极端情况是什么？
• 确认一个具体的 Given/When/Then 示例

相关能力共享工作流时合并到同一轮。大的能力域拆分到多轮。

轮次 N+1：非功能需求

按相关性分 1-2 轮批量探测 NFR：

类别（ISO 25010）	探测
性能	响应时间目标？吞吐量？并发用户？
可靠性	可用性目标？恢复时间？数据丢失容忍度？
易用性	无障碍要求？可学习性标准？
安全性	认证方式？授权模型？数据加密？
可维护性	模块化约束？测试覆盖率目标？
可移植性	平台限制？浏览器支持？
可扩展性	当前负载？目标负载？增长时间线？

跳过明显不相关的类别。规则：每个 NFR 必须有可度量的标准。"快" -> "在 1000 并发用户下 p95 响应时间 < 200ms"。

轮次 N+2：约束、假设与接口

合并为一轮（最多 4 个问题）：

• 硬限制（托管、预算、许可证、法规、现有系统）
• 假设为真的是什么？假设错误会破坏什么？
• 要集成的外部系统？协议和数据格式？
• 需要保持向后兼容的现有 API？

轮次 N+3：术语表

必要时问一轮：

• 有潜在歧义的领域术语？
• 需要统一的同义词？需要区分的同形异义词？

何时停止： 当你能描述每个功能能力、其验收标准、所有带可度量阈值的 NFR、所有约束和假设 — 无需猜测时，进入步骤 3。

步骤 3：分类需求

将捕获的需求组织到以下类别：

类别	ID 前缀	描述
功能	FR-001	可观测的系统行为
非功能	NFR-001	带可度量标准的质量属性
约束	CON-001	限制解决方案空间的硬限制
假设	ASM-001	假定为真的信念；记录失效风险
接口	IFR-001	外部系统契约
排除	EXC-001	明确不在范围内

步骤 4：使用 EARS 模板编写需求

对每个功能需求应用 EARS（Easy Approach to Requirements Syntax）模板：

模式	模板	适用场景
普遍性	系统应当 <动作>。	始终有效的行为
事件驱动	当 <触发条件> 时，系统应当 <动作>。	响应用户/系统事件
状态驱动	当处于 <状态> 时，系统应当 <动作>。	行为依赖模式/状态
异常行为	如果 <条件>，则系统应当 <动作>。	错误处理、容错
可选	当 <功能/配置> 启用时，系统应当 <动作>。	可配置/可选能力

对每个需求还需编写：

• 验收标准 — 至少一个具体的 Given/When/Then 场景
• 优先级 — Must / Should / Could / Won't（MoSCoW）
• 来源 — 追溯到哪个干系人需要或用户故事

对于现有项目改动，必须把 CURRENT-STATE.md 中“当前变更关注点”的结果吸收到需求文档中，至少明确：

• Current State
• Affected Areas
• Out of Scope

步骤 5：验证 SRS 质量

对照 8 项质量属性（IEEE 830 / ISO 29148）运行系统化质量检查：

5a. 逐需求检查

对每个需求验证：

#	属性	检查	红线信号
1	正确	追溯到已确认的干系人需求？	孤立需求（镀金）
2	无歧义	两个读者会写出相同的测试用例？	模糊词："快"、"健壮"、"用户友好"、"直觉"、"灵活"
3	完整	所有输入、输出、错误情况、边界已定义？	"包括但不限于..."、无界列表
4	一致	与其他需求无矛盾？	时间冲突、格式冲突
5	有排序	有 MoSCoW 优先级？	所有都是"高优先级"
6	可验证	能写出通过/失败测试？	"系统应易于使用"（无指标）
7	可修改	在且仅在一处表述？	跨章节重复
8	可追溯	有唯一 ID + 来源链接？	缺少 ID 或孤立

5b. 反模式检测

在展示前扫描完整 SRS 中的这些反模式并修复：

反模式	检测信号	修复
模糊形容词	"快"、"大"、"可扩展"、"可靠" 无数字	用可度量标准量化
复合需求	"和"/"或"连接两个不同能力	拆分为独立需求
设计泄露	实现词汇："类"、"表"、"端点"、"算法"	重写为可观测行为
无主体被动语态	"数据应被验证" — 谁来验证？	添加明确主体："系统应..."
TBD / TBC	未解决占位符	与用户解决或标记为开放问题
缺少否定	仅指定正面情况	添加错误/边界/安全情况
不可测 NFR	NFR 无可度量阈值	添加具体指标 + 度量方法

5c. 完整性交叉检查

• 每个功能领域至少有一个错误/边界情况
• 所有外部接口有数据格式 + 协议规定
• 所有 NFR 有度量方法，不仅是目标值
• 术语表覆盖需求中使用的所有领域特定术语
• 排除范围章节明确列出推迟的功能

步骤 6：展示并审批 SRS

对非简单项目，逐节展示并获得审批：

1. 目的、范围与排除 — 边界和不包含的内容
2. 术语表与用户画像 — 共享词汇和用户理解
3. 功能需求 — 核心能力及验收标准
4. 非功能需求 — 带指标的质量属性
5. 约束、假设与接口 — 硬限制和外部契约

逐节展示。等待用户反馈。整合变更后再进入下一节。

简单项目（< 5 个功能需求）：合并所有章节为单次审批步骤。

步骤 7：保存 SRS 文档

将审批通过的 SRS 保存到 docs/changes/<change-id>/requirements.md。

模板使用

读取步骤 1 中找到的模板：

1. 保留模板的标题结构
2. 用审批通过的 SRS 内容替换每个标题下的指导文本
3. 顶部添加元数据（Date、Status、Standard、Template 路径）
4. 模板中未覆盖的章节：标记"[不适用]"
5. 审批内容无对应模板章节：附加为"补充说明"

步骤 8：过渡到 UCD

SRS 文档保存并提交后：

1. 总结下一阶段需要的关键输入：
   • 功能需求数量和优先级分布
   • 影响架构选择的关键约束
   • 影响技术选型的 NFR 阈值
   • SRS 是否包含 UI 相关功能需求（design 阶段据此判断是否执行 UCD 子步骤）
2. 进入 vibeflow-design

规模适配

项目规模	功能需求数	深度
微型	1-5	单页 SRS，合并审批步骤
小型	5-15	标准 SRS，2-3 个审批章节
中型	15-50	完整 SRS 含所有章节，逐节审批
大型	50-200+	完整 SRS + 接口规格 + 领域模型

红线

合理化借口	正确响应
"太简单不需要 SRS"	运行轻量 SRS（单次审批步骤）
"用户已经描述了他想要的"	用户描述是原始输入；SRS 添加结构、完整性、可测试性
"我可以在设计时弄清需求"	需求定义 WHAT；在 HOW 中发现它们会导致返工
"NFR 不适用于此项目"	每个项目至少有隐含的性能/可靠性需求 — 使其显式
"术语表是显而易见的"	对谁显而易见？定义用户和开发者可能有不同理解的每个术语
"我先从正常路径开始"	错误情况、边界和否定场景必须现在捕获

集成

调用者： vibeflow-router（requirements 阶段） 链接到： vibeflow-design（SRS 审批后） 产出： docs/changes/<change-id>/requirements.md