software-requirements

软件需求分析

编写专业、全面且明确无歧义的软件需求文档，供开发团队据此构建、QA 团队据此测试，并让利益相关者能够放心批准。

输入处理

确定输入类型并相应作答：

1. 非正式描述 —— 用户用日常语言描述想要构建的内容（例如：“我需要一个带密码重置功能的登录页面”）。按照需求探索和编写阶段，将其扩展为结构化需求。

2. 待评审的现有文档 —— 用户提供现有需求文档以供评审。跳过需求探索，进入需求评审模式。

3. “为我编写 X”请求 —— 用户明确要求编写特定类型的文档（例如：“为我的支付系统编写一份 SRS”）。如果范围明确，则跳过需求探索；进入文档类型选择和编写阶段。

4. 用户故事功能请求 —— 用户希望为特定功能或冲刺编写用户故事和验收标准。使用文档类型指南中的用户故事模板。

需求探索阶段（阶段 1）

在编写任何需求之前，必须通过以下 7 个问题收集背景信息。如果用户已提供部分信息，应确认已知内容，并只询问尚缺的信息。不要跳过此阶段。

请用户澄清：

1. 系统/产品：要构建什么？哪些内容明确属于范围内，哪些不在范围内？
2. 利益相关者：最终用户、管理员、运营人员、外部系统和监管机构分别有哪些？
3. 问题：要解决什么具体问题？为什么需要它？
4. 约束条件：技术栈、预算、时间线、监管要求（GDPR、HIPAA、PCI-DSS、SOX、ADA）、需要集成的现有系统，以及遗留依赖项？
5. 文档类型：需要哪种文档？（如果不确定，请根据背景信息提出建议。）
6. 交付格式：.docx、Markdown、wiki、JIRA 用户故事，还是 Confluence 页面？
7. 现有材料：是否有线框图、用户研究、竞争分析或可供参考的现有文档？

明确指出每项假设，并在最终文档中列出。

文档类型选择（阶段 2）

在此阶段之前，请先阅读 references/document-types.md。

根据需求探索阶段收集的信息，使用决策启发式规则推荐合适的文档类型。参考文件包含：

• 选择表（SRS、PRD、BRD、FRD、用户故事、用例）
• 快速决策逻辑
• 全部 6 种文档模板

需求编写（阶段 3）

在进入此阶段之前，请阅读 references/requirement-writing-rules.md。

编写需求时，请遵循以下规则：

• 语言规则：所有需求均须使用 “shall”（强制）、“should”（建议）或 “may”（可选）。使用主动语态。单条需求中不得使用 “and” 或 “or” 合并多种行为。明确指定具体数值（例如，“在 2 秒内”，而非“快速”）。
• 需求 ID 格式：使用分层 ID，例如 FR-AUTH-001、NFR-PERF-001、DR-001、IR-API-001
• 每条需求的必填字段：ID、描述、理由、优先级（Must/Should/Could/Won't）、来源、验收标准、依赖项、备注
• 避免使用禁用词：“should generally”、“as appropriate”、“etc.”、“and/or”、“user-friendly”、“fast”、“efficient”、“robust”、“seamless”、“intuitive”、“various”、“some”、“relevant”、“adequate”、“reasonable”、“timely”、“properly”、“correctly”、“easy”、“simple”、“normal”

将每处禁用词替换为具体、可衡量的陈述。

输入处理规则：

• 对于每个输入：指定类型、格式、有效范围、必填还是可选、默认值、最大长度
• 对于每个输出：指定格式、目标位置、时间要求、错误格式
• 对于每项操作：指定发生故障、超时、数据无效、并发访问或取消时的处理方式

将非正式描述至少扩展到原文的 3 倍长度。例如，一句功能描述应生成 20 条以上的需求，涵盖功能、安全性、性能、无障碍性和合规性。

必须涵盖的领域（阶段 3 续）

对于每份文档，请确保涵盖以下所有类别：

A) 功能需求（FR）：核心功能、业务规则、数据验证、错误处理、状态转换、批处理、通知

B) 非功能需求（NFR）：始终包括以下所有内容：

• 性能：页面加载时间、API 响应时间、吞吐量、查询延迟
• 可扩展性：最大并发用户数、最大数据量、增长率
• 安全性：身份验证、授权（RBAC/ABAC）、加密、审计日志、会话管理、防范 CSRF/XSS/SQLi 攻击
• 可靠性：运行时间目标、MTTR、MTBF、故障转移策略、灾难恢复
• 无障碍性：WCAG 等级（最低 2.1 AA）、键盘导航、屏幕阅读器、色彩对比度
• 易用性：可学习性、错误恢复、用户满意度基准
• 可维护性：日志标准、监控、部署、代码质量
• 可移植性：浏览器及版本、操作系统、设备、离线支持
• 合规性：GDPR、HIPAA、PCI-DSS、SOX、ADA、COPPA、CCPA、行业法规
• 国际化：语言、区域设置、RTL 支持、Unicode 处理

C) 接口需求（IR）：用户界面、带架构的 API 端点、硬件接口、第三方集成

D) 数据需求（DR）：数据模型、保留政策、迁移策略、备份流程、隐私分类、数据质量规则

验证阶段（阶段 4）

在进入此阶段前，请阅读 references/validation-checklist.md。

根据每项需求执行验证清单：

• 歧义扫描：查找禁用词，并将其替换为具体、可衡量的表述
• 可测试性检查：能否为每项需求编写通过／失败测试？
• 完整性检查：是否考虑了空值／空输入、网络故障、超时、磁盘空间已满、格式错误的数据、并发访问、API 不可用、权限错误、会话过期等情况？
• 矛盾检查：是否有两项需求无法同时满足？
• 接口检查：是否完整说明了所有外部接口？
• NFR 检查：是否涵盖了所有非功能类别？
• 优先级检查：是否为每项需求标注了优先级（必须／应该／可以／不会）？
• 术语表检查：是否定义了所有特定领域的术语？
• 假设检查：是否明确列出了所有假设？
• 范围检查：是否明确列出了范围外的事项？
• 可追溯性检查：每项需求是否都能追溯到一个业务目标？
• 未决问题：是否记录了未解决事项的负责人和目标解决日期？

在继续交付前修复所有问题。

交付阶段（阶段 5）

交付物应包含：

1. 主要需求文档——使用阶段 2 的模板，包含所有需求，按类别组织，并标注 ID、优先级、验收标准和交叉引用

2. 编号的假设清单——列出在调研和规划过程中发现的所有隐含假设，并对每项进行风险评估

3. 未决问题日志——记录未解决事项，包含以下列：ID、问题、负责人、目标日期、状态

4. 附录：

   • 需求可追溯性矩阵（需求 ID → 业务目标 → 测试用例 ID）
   • 所有特定领域术语的术语表
   • 变更日志（版本、日期、作者、变更内容）

5. 版本块：随着文档逐步完善，从 v0.1 草稿更新为 v1.0 已批准

需求审查模式

当用户提供现有需求文档供审查时：

1. 先通读整份文档，再发表评论
2. 根据 7 项质量原则逐项检查需求（参见 references）
3. 标记问题并提供精确引用：
   • 歧义：引用含糊的表述 → 提供具体的替换文本
   • 缺失：指出缺口 → 建议用于填补缺口的需求文本
   • 矛盾：引用相互冲突的两个需求 ID → 建议解决方案
   • 不可测试：说明原因 → 提供可测试的改写版本
   • 不完整：指出缺失的错误情况、边界情况或 NFR 类别
4. 评定每个问题的等级：
   • 严重：阻碍开发
   • 主要：导致返工
   • 次要：完善润色
5. 总结：按严重程度统计问题数量、列出优先级最高的 5 项修复事项，并给出总体质量评分（1-10）
6. 在回复中完整改写最差的需求

输出规则

• 需求描述的是“是什么”，而不是“如何做”。应写“系统应对用户进行身份验证”，而不是“使用 OAuth 2.0 和 JWT”（除非技术确实是约束条件）。
• 扩展非正式描述时，生成的需求数量至少应为用户所述数量的 3 倍。
• 末尾始终包含“缺失内容／需要利益相关者提供意见”部分。
• 始终包含编号的假设清单。
• 始终包含有负责人和目标日期的未决问题日志。
• 对文档进行版本管理（v0.1 草稿 → v1.0 已批准），并维护变更日志。
• 在全文中通过 ID 交叉引用相关需求。
• 对于正式文档：生成包含目录、标题、页码和需求表格的文档。
• 对于敏捷工件：格式应适合直接导入 JIRA／Linear／Shortcut。

指南

• 不要跳过探索。不要想当然。明确指出每一项假设。
• 绝不使用禁用词。用具体、可衡量的表述替换它们。
• 按 ID 交叉引用相关要求。例如：“会话管理要求请参见 FR-AUTH-001。”
• 重写非正式描述时，指出其中未明示的假设——逐一列出并针对每项提问。
• 将复合要求拆分为只涉及单一行为的原子要求。
• 始终根据领域补充安全性、无障碍性和合规性要求，即使用户没有明确提出。
• 对于非常庞大的文档（>100 条要求），按逻辑章节拆分，并提供汇总摘要。
• 当用户意图不明确时，明确说明假设，而不是默默做出判断。