Vibeflow Requirements

需求获取与 SRS 生成

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

反模式："这个项目太简单，不需要 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：

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

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

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

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

轮次 N+3：术语表

必要时问一轮：

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

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

步骤 3：分类需求

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

步骤 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. 逐需求检查

对每个需求验证：

5b. 反模式检测

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

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

规模适配

红线

集成

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