# Vibeflow Requirements

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

- Skill: `ttttstc/vibeflow-requirements` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ttttstc/vibeflow-requirements`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ttttstc/vibeflow-requirements/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ttttstc (https://skillmd.com/u/ttttstc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ttttstc/vibeflow-requirements

---


# 需求获取与 SRS 生成

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

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

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