Requirements Analysis
导言
需求分析报告是一份开发前的决策合同。它要在投入主要研发资源之前回答五个问题：客户真正需要什么，需求由哪些部分组成，有哪些技术路线，项目是否可行且值得做，以及每条需求究竟如何定义和验收。
即使报告是在功能已经穿刺或实现之后补写，正文也不应从“已经完成了什么”出发。代码、测试和实验只能作为分析者校验接口、约束、技术可行性和估算边界的材料；最终报告仍应冻结在开发决策时点，使用“应、必须、拟采用、计划验证”的语态，不写实现完成率、测试通过情况或上线效果。
本文按六个阶段组织完整方法：识别真实需求、拆解需求组成、调研与选择技术方案、评估可行性/工作量/价值、定义需求与验收、确定优先级并建立基线。每个阶段都明确要消除的不确定性、适用方法、输出物和评审门。
职责边界¶
需求分析关注的不是“软件现在长什么样”，而是是否应该开发，以及开发什么才算正确。它的叙事时点位于正式开发之前，输出服务于立项、范围确认、方案决策、排期和验收。
| 产物 | 核心问题 | 可以包含 | 不应替代 |
|---|---|---|---|
| 需求分析报告 | 为什么做、为谁做、做什么、采用哪类路径、值不值得、如何验收 | 用户与场景、问题根因、需求目录、候选方案、可行性、工作量、价值、验收条件 | 实现说明、测试报告、上线复盘 |
| 技术方案/设计文档 | 选定方案具体怎样实现 | 架构、模块、接口内部设计、数据结构、调用流程、部署设计 | 客户需求与立项价值判断 |
| 开发计划 | 谁在什么时候交付 | WBS、人员、里程碑、依赖、缓冲 | 需求必要性与技术可行性论证 |
| 测试与验收报告 | 交付结果是否满足合同 | 测试结果、缺陷、指标实测、验收结论 | 开发前的验收标准定义 |
| 复盘报告 | 实际发生了什么、为什么有偏差 | 完成情况、故障、经验、改进项 | 原始需求分析报告 |
技术洞察可以进入需求分析，但只承担候选方案与可行性判断，不能反过来决定客户“应该需要”什么。
| 视角 | 核心问题 | 主要证据 | 主要输出 |
|---|---|---|---|
| 需求分析 | 谁遇到什么问题，影响多大，希望改善到什么程度 | 访谈、观察、业务流程、工单、日志、业务数据、约束 | 问题陈述、需求规格、优先级、验收合同 |
| 技术洞察 | 现有技术为何不满足，有哪些路线，各自边界是什么 | 标准、论文、官方文档、代码、Profiling、基准、PoC | 技术基线、候选方案、权衡、技术风险 |
| 技术设计 | 已选路线如何落实到系统 | 架构与接口设计、数据流、组件职责 | 可实施设计与开发任务 |
完成情况不进入需求正文
“代码已经接入新算子”“测试已经通过”“线上吞吐提升 20%”属于实现、验证或复盘结论。需求报告只写“系统应在什么条件下选择候选路径”“验收时用什么环境和指标判断”“达不到阈值如何处置”。
容易混淆的原因¶
当用户只提供一条穿刺需求和已完成代码时，分析者很容易沿着代码结构倒推需求。下面这张图描述的是需求考古或复盘取证，它可以帮助分析者发现接口、约束和遗漏，但不是需求报告的主流程。
正确做法是把这些材料放在分析者的工作底稿中：用代码确认当前系统边界，用测试发现可能遗漏的异常场景，用实验校准技术估算；一旦进入正式需求报告，就回到开发前问题，不描述最终完成状态。
总体决策链¶
ISO/IEC/IEEE 29148:2018 将需求工程定义为贯穿生命周期的工程过程，并给出需求相关信息项的内容与格式指导。NASA Systems Engineering Handbook 则把干系人期望、技术需求、逻辑分解和设计方案视为相互迭代的系统设计过程：方案必须同时接受用户期望、预算和进度约束的检验，而不是先写需求、再单向交给开发。NASA Systems Engineering Handbook
面向 AI 开发，可以把这条迭代链收束为：
flowchart LR
A["机会或问题信号"] --> B["真实用户与场景"]
B --> C["问题影响与根因"]
C --> D["需求分解与范围"]
D --> E["候选技术方案"]
E --> F["可行性、工作量、价值"]
F --> G{"是否值得立项"}
G -->|"否"| H["拒绝、延后或继续调研"]
G -->|"是"| I["需求定义与验收合同"]
I --> J["优先级、版本范围与基线"]
J -. "新证据或约束变化" .-> B这里的关键不是方法越多越专业，而是每种方法都要消除一个明确的不确定性：
- 不知道谁是真正用户，用干系人分析、访谈和现场观察。
- 不知道表面功能背后的任务，用 Jobs to Be Done（JTBD）和 5 Whys。
- 不知道需求是否完整，用场景、用例、功能树、质量属性和接口分析。
- 不知道技术能否做到，用技术扫描、代码研究、基准和 PoC。
- 不知道是否值得做，用价值—成本—风险分析、RICE 或 WSJF。
- 不知道做到什么程度，用质量属性场景和 Given-When-Then。
阶段一：识别真实需求¶
第一阶段不是记录客户提出的功能，而是识别谁在什么场景遇到了什么问题，问题造成了多大影响，客户真正希望取得什么进展。
获取原始诉求¶
按场景选择需求获取方法：
- 访谈：适合追问目标、现行流程、痛点、绕行方式、不可接受结果和成功定义。客户、直接用户、产品、开发、测试、运维的答案应分别记录，避免把某一方意见冒充共识。
- 现场观察与情境调查：适合训练平台、运维系统、工业软件等复杂工作流。观察“实际上怎样操作”，尤其关注复制粘贴、手工脚本、重复确认和异常绕行。
- 需求工作坊/JAD：适合多团队边界、接口责任和优先级存在冲突的情况。输出共识、分歧、待确认项和决策人，不只输出会议纪要。
- 文档与现有系统分析：工单、投诉、日志、事故、历史需求、接口和竞品可以提供频率与影响证据。代码只能说明当前行为和约束，不能单独证明用户需求。
- 问卷：适合统计问题覆盖面和群体差异，不适合独立挖掘复杂根因。
从功能请求追到真实任务¶
用户常用一个熟悉的解决方案表达问题，例如“增加日志下载”“换成某个新模型”“接入一个新算子”。分析者要把方案句还原成任务句。
JTBD 可以写成：
例如，表面需求是“自动下载所有 Rank 日志”，真实任务可能是：
当分布式训练失败时，训练工程师需要在十分钟内判断首个异常来自环境、框架、模型还是硬件，从而减少集群空转，同时避免遗漏跨节点的关键错误。
再用 5 Whys、问题树或假设驱动分析区分症状与原因。5 Whys 适合简单因果链；复杂 AI 系统应并列记录数据、模型、算子、通信、资源、调度和流程假设，并为每个假设设计能区分它们的证据。
固化问题与目标¶
本阶段至少输出：
| 交付物 | 必须包含 |
|---|---|
| 干系人地图 | 用户、客户、决策者、运维者、维护者、受影响团队及其权责 |
| 现状场景 | 触发、参与者、步骤、输入输出、绕行、失败和恢复 |
| 问题陈述 | 当前状态、期望状态、差距、影响范围、频率、严重度 |
| 根因/假设账本 | 已确认原因、竞争假设、区分性证据、待确认项 |
| 目标树 | 业务/工程结果 → 用户能力 → 系统能力，不按代码模块拆 |
评审门：如果还不能说清目标用户、触发场景、当前损失、期望结果和不做的后果，就不能进入技术选型。新模型、新算法或新硬件的出现只是机会信号，不自动构成需求。
阶段二：拆解需求组成¶
第二阶段把“想解决的问题”展开成完整、互不混淆、可以进一步估算和验收的需求集合。
先划边界再拆功能¶
用 系统上下文图确认系统控制什么、依赖什么、与哪些人和外部系统交互；再根据问题选择模型：
- 业务流程图/泳道图：分析步骤、责任交接和跨团队边界。
- 用例：记录参与者、前置条件、主成功流程、异常流程和后置条件。
- 状态机：分析对象状态、事件、守卫条件和非法转换。
- 时序图：分析组件消息顺序、超时和重试。
- DFD/数据血缘：分析数据来源、处理、存储、消费和合规边界。
- 功能树/FBS/FAST：把目标拆成用户能力和可验证行为，不照抄源码目录。
需求分类可以使用稳定 ID：
| 类型 | ID | 回答的问题 | 例子 |
|---|---|---|---|
| 业务需求 | BR-* |
为什么值得投入 | 将训练故障平均定位时间从两天降低到两小时 |
| 用户需求 | UR-* |
用户要完成什么任务 | 工程师能查看跨节点统一排序的异常时间线 |
| 功能需求 | FR-* |
系统必须提供什么行为 | 收集并关联所有 Rank 的标准输出和设备日志 |
| 质量需求 | QR-* |
行为要达到什么水平 | 在 1024 Rank 下五分钟内完成聚合，采集率不低于 99.9% |
| 接口需求 | IR-* |
与外部怎样交互 | 输入、输出、协议、版本、错误码、超时和兼容语义 |
| 约束 | CON-* |
哪些边界不能突破 | 公开 API 不变、附加开销不超过批准阈值、支持离线环境 |
主动补齐异常与质量¶
只拆正常功能会漏掉大量真实成本。每个用例至少检查：
- 正常输入和主成功路径；
- 边界值、空值、极值和不支持组合；
- 部分失败、超时、重试、幂等和恢复；
- 兼容、升级、降级、回退和退役；
- 权限、安全、隐私、审计和供应链；
- 性能、可靠性、可维护性、可观测性和成本。
ISO/IEC 25010:2023 可用作产品质量维度的检查表，但不应把标准术语机械复制成需求。只有绑定具体刺激、环境、系统响应和测量阈值后，质量属性才可评审。
评审门：每个目标都能下钻到用户任务和系统需求；正常、异常、接口、质量和约束要么有定义，要么明确列入非目标；不同需求之间没有重复、冲突或隐含实现方案。
阶段三：调研并选择技术方案¶
技术方案调研的职责是回答：需求能否实现，有哪些可选路径，每条路径依赖什么前提、带来什么收益和代价。它不能跳过前两阶段直接从“新技术很先进”得出立项结论。
建立技术基线¶
先描述现有能力与瓶颈：
- 当前流程、架构和技术栈能够满足哪些需求，不能满足哪些需求；
- 瓶颈位于能力、精度、时延、吞吐、显存、通信、稳定性、兼容、运维还是成本；
- 瓶颈依据来自哪里，是否能复现，适用环境和数据分布是什么；
- 不改变系统时可以接受的上限是什么。
只有瓶颈被量化后，技术扫描才有筛选标准。调研可以覆盖标准、论文、官方文档、开源代码、竞品、供应商方案、内部复用能力和自研路径，但每个候选都要记录成熟度、依赖、适用边界和证据质量。
构造可比较候选¶
至少保留以下基准项：
- 不做/维持现状：用于计算延迟成本和机会成本。
- 最小改造：只解决 Must 问题，验证是否能以较低成本获得主要价值。
- 目标方案：在需求、质量和演进上综合适配的路径。
- 替代路线：购买、复用、集成、自研或流程优化等真正不同的机制。
候选比较不能只列功能，要用同一组决策准则：
| 准则 | 要检查的内容 |
|---|---|
| 需求适配 | Must 覆盖率、异常场景、接口与质量要求 |
| 技术可行性 | 原理、依赖、性能上限、精度、扩展性、成熟度 |
| 交付可行性 | 人才、资源、工期、供应链、环境和协作边界 |
| 生命周期成本 | 研发、迁移、运行、运维、升级、兼容和退出成本 |
| 风险 | 失败模式、可探测性、缓解措施和残余风险 |
| 可逆性 | 是否可灰度、回退、替换和保留旧路径 |
用 PoC 降低关键不确定性¶
PoC 不是提前开发正式功能，而是为一个关键决策设计最小实验。例如：新算子是否支持目标 Shape，某方案在指定硬件上能否把显存峰值降到目标区间，某模型在目标数据上是否满足最低能力与安全护栏。
PoC 结论必须限定模型、数据、硬件、软件、精度、并行策略、样本、预热、重复次数和统计口径。PoC 的候选结果可以支持“技术上值得进入正式开发”，不能直接变成产品验收结果。
技术决策最终形成一份 Decision Record：候选、评价准则、证据、选择理由、拒绝理由、关键假设、代价、可逆性和重审触发器。架构质量冲突明显时，可使用 ATAM 风格的效用树和质量场景来暴露风险、敏感点与权衡点。
评审门：推荐方案必须满足所有 Must 需求；关键技术假设已有证据或明确 PoC 计划；没有把“实现方便”“已有代码”冒充用户价值，也没有因为某项技术新就忽略维持现状和低成本替代方案。
阶段四：评估可行性、工作量与价值¶
这一阶段回答三个不同问题：能不能做、要付出多少、付出是否值得。三者必须分别分析，再合并成 Go / No-Go / 继续调研决策。
可行性评估¶
| 维度 | 核心问题 | 常用方法 |
|---|---|---|
| 技术可行性 | 原理、性能、精度、规模和边界能否满足 Must | PoC、基准、代码/架构评审、成熟度评估 |
| 数据可行性 | 数据是否存在、可用、合法、代表目标分布 | 数据盘点、质量剖析、许可与隐私审查 |
| 资源可行性 | 算力、存储、网络、环境、预算是否可获得 | 容量模型、成本模型、资源排期 |
| 交付可行性 | 团队能力、依赖、工期和协作是否允许 | WBS、依赖图、关键路径、能力差距分析 |
| 运营可行性 | 部署、观测、支持、回退和维护是否可承担 | 运维评审、Premortem、风险登记 |
| 合规可行性 | 安全、隐私、许可证、行业规则是否满足 | 合规检查、威胁建模、供应链审查 |
任何一项不可行都应产生明确处置：修改范围、替换方案、增加前置项目、继续 PoC，或者停止立项。
工作量估算¶
工作量不是一个没有置信区间的“人天数”。先按可交付能力拆 WBS，再估算设计、开发、测试、数据、迁移、运维、文档和跨团队协作。
常用方法可以组合：
- 类比估算：有相似项目时快速建立量级，但要写清差异修正。
- 自下而上估算：对已拆清的工作包分别估算，再加依赖和集成成本。
-
三点估算：为高不确定任务记录三个独立估计，并保留原始区间：
符号 含义 产生者 使用位置 状态 O乐观工作量 负责该工作包的估算者 三点期望值与区间下界参考 控制量，不是实测值 M最可能工作量 负责该工作包的估算者 三点期望值 控制量，不是实测值 P悲观工作量 负责该工作包的估算者 三点期望值与区间上界参考 控制量，不是实测值 E加权期望工作量 由 O/M/P计算汇总工作包估算 计算结果，不替代原始区间 一个常用的 PERT 加权表达是
E = (O + 4M + P) / 6。它只把估算者的三个判断压缩成期望值，不代表真实工期服从某个已校准分布。 - Spike/PoC：对未知 API、模型能力、性能上限或硬件兼容先买信息，再缩小估算区间。 - 关键路径与缓冲：区分可并行工作和阻塞依赖，不把所有人天直接除以人数。
估算表至少记录：工作包、范围假设、负责人角色、依赖、O/M/P、风险缓冲、证据来源和失效条件。
是否值得做¶
价值评估应同时看：
- 用户和业务结果：覆盖人数、问题频率、时间/成本节省、质量和满意度；
- 工程与战略价值：解除关键阻塞、平台复用、生态适配、供应风险降低、能力积累；
- 延迟成本：不做或晚做会损失什么，窗口何时关闭；
- 总成本：研发、迁移、运行、运维、升级、学习和退出；
- 风险调整：收益置信度、失败概率依据、最坏影响和可逆性。
MoSCoW 适合表达版本承诺；RICE 适合有覆盖人数和影响数据的产品需求；WSJF 适合比较延迟成本与工作规模；底层框架和基础设施还应加入阻塞范围、复用程度和战略依赖，避免仅按用户数量低估价值。
可以用统一决策表保留判断依据：
| 方案 | 预期价值 | 总工作量/成本 | 关键风险 | 收益置信度 | 延迟成本 | 可逆性 | 建议 |
|---|---|---|---|---|---|---|---|
| 维持现状 | 基线 | 低 | 问题持续 | 高 | 待量化 | 高 | 比较基准 |
| 最小改造 | 覆盖 Must | 中低 | 能力上限 | 中高 | 可部分降低 | 高 | 可作为首版 |
| 目标方案 | 覆盖 Must/Should | 中高 | 技术与交付风险 | 取决于 PoC | 主要降低 | 中高 | 条件式推荐 |
评审门：报告必须给出推荐、拒绝、延后或继续调研之一，并写清成立条件。没有基线、工作量区间、价值来源和关键风险时，不应输出看似精确的综合分数。
阶段五：定义需求与验收¶
通过立项门后，把需求写成开发和验收共同遵守的合同。每条需求应满足：必要、单一、明确、一致、可行、可验证、可追踪，并避免过早规定内部实现。
单条需求结构¶
| 字段 | 说明 |
|---|---|
| ID 与类型 | BR/UR/FR/QR/IR/CON，稳定且唯一 |
| 规范性陈述 | 使用“系统应/必须”，只表达一个行为或约束 |
| 场景与理由 | 为什么需要，服务哪个用户任务和目标 |
| 范围 | 适用对象、环境、数据、版本和明确排除项 |
| 优先级 | Must/Should/Could/Won't 或其他批准规则 |
| 验收方法 | 分析、评审、演示、测试或运行测量 |
| 验收条件 | 前置、触发、可观察结果、阈值和容差 |
| 责任人 | 需求、技术、验证和最终验收责任 |
质量需求使用质量属性场景：
例如：
在支持的模型、BF16 精度和指定序列区间内，当 Attention 输入满足新路径约束时，系统应在公开 API 不变的条件下完成计算；与批准基线相比，端到端吞吐不低于目标阈值，峰值显存不高于目标阈值，输出误差不超过责任人批准边界。不支持的 Shape 必须进入兼容路径并产生可检索原因。
AI、模型、算法和算子需求还要提前冻结评测合同：
| 维度 | 必须定义 |
|---|---|
| 任务边界 | 目标人群/数据分布、场景、排除项 |
| 版本来源 | 模型、权重、数据、代码、许可证和供应链 |
| 对照条件 | baseline/candidate、硬件、软件、精度、并行、seed |
| 测量协议 | 样本、预热、重复次数、统计口径、失败处理 |
| 指标分层 | 能力、系统、业务结果和护栏指标 |
| 判定规则 | 阈值、容差、回归预算、优先级和一票否决项 |
| 安全与回退 | 失败分类、人类接管、fallback 和停止条件 |
Given-When-Then 适合把验收写成用户或外部系统可观察的行为：Cucumber Gherkin Reference
Scenario: 不支持的 Shape 安全回退
Given 训练任务使用公开支持的模型 API，但输入 Shape 不满足候选算子约束
When 系统执行 Attention 计算
Then 系统应使用兼容路径完成计算，并产生包含回退原因的可检索事件
定义验收，不填写结果
需求报告中的验收章节规定测试对象、环境、数据、步骤、阈值、证据形式和签字人；“通过/失败/部分满足”应在后续测试或验收报告中填写。
评审门：所有 Must 需求都有可观察验收条件和责任人；“更快、更省、更智能、精度无损、稳定可用”等词都已转换为有环境边界的指标。
阶段六：优先级、范围与基线¶
最后把经过论证的需求变成一个可执行但仍保持需求视角的版本基线。
- 确定优先级：综合用户价值、依赖、风险、工作量和延迟成本，避免所有需求都标 Must。
- 切分首版范围：选择能够独立验证核心价值的最小闭环，而不是随意砍掉测试、观测和回退。
- 声明非目标：明确当前版本不解决的用户、场景、平台、数据和质量范围。
- 记录依赖与风险：外部团队、硬件、数据、供应商、合规和前置能力都要有责任人及触发条件。
- 建立正向追踪：连接问题、目标、用户需求、系统需求、候选方案依据和验收场景。
- 建立变更控制：需求、阈值或约束变化时，重新评估方案、工作量、价值和验收，不在开发中静默漂移。
开发前追踪链应当是：
它不包含代码完成情况和测试结果。后续设计、开发和测试可以扩展同一组稳定需求 ID，但属于下游产物。
评审门：所有 Must 需求都能回到真实问题，也都能前向连接到验收；首版范围能够独立产生价值；未决问题、假设、非目标和批准条件在首页可见。
完整报告结构¶
一份面向开发前决策的完整需求分析报告，可以按下列目录组织。章节可以裁剪，但被裁剪的内容要写明原因和风险。
| 章节 | 必须回答 | 核心交付物 |
|---|---|---|
| 0. 文档控制 | 谁负责、分析截止何时、等待什么决策 | 版本、状态、责任人、评审记录 |
| 1. 执行摘要 | 为什么现在考虑、建议做不做、主要条件是什么 | 一页 Go/No-Go/继续调研结论 |
| 2. 背景与机会 | 什么变化或问题触发分析 | 机会说明、现状基线、反事实 |
| 3. 客户与真实需求 | 谁在什么场景需要什么结果 | 干系人、访谈/观察结论、JTBD |
| 4. 问题与根因 | 症状、影响和根因分别是什么 | 问题树、假设账本、目标树 |
| 5. 范围与上下文 | 系统控制什么、不控制什么 | Context、业务流程、非目标 |
| 6. 需求拆解 | 需求由哪些能力和场景组成 | 用例、功能树、BR/UR/FR/QR/IR/CON 草案 |
| 7. 技术基线与候选 | 现有技术为何不够，有哪些路线 | 瓶颈、技术扫描、候选与证据 |
| 8. 可行性分析 | 技术、数据、资源、交付、运营、合规能否成立 | PoC、容量/成熟度/依赖评估 |
| 9. 工作量与价值 | 要投入多少，收益和延迟成本多大 | WBS、三点估算、价值—成本—风险 |
| 10. 方案决策 | 为什么选择或拒绝某条路线 | 权衡矩阵、Decision Record、重审条件 |
| 11. 需求规格 | 每条需求具体要求什么 | 已批准需求目录、理由、优先级、责任人 |
| 12. 验收计划 | 怎样证明每条需求满足 | 质量场景、评测合同、GWT、验收矩阵 |
| 13. 风险与依赖 | 什么会使计划失败，如何降低风险 | 风险登记、依赖、缓解和停止条件 |
| 14. 范围与版本 | 首版做什么、暂不做什么 | Must/Should/Could/Won't、阶段边界 |
| 15. 追踪与审批 | 决策链是否闭合，谁批准 | 开发前追踪矩阵、未决问题、签字条件 |
这份结构刻意不包含“实现对应、测试结果、上线指标和完成结论”。这些内容应分别进入设计文档、开发记录、测试/验收报告和复盘报告。
AI 技术机会案例¶
假设一个新高性能 Attention 算子出现，团队希望评估是否接入。正确的需求分析不是从“代码已经能跑”开始，而是从开发前决策开始：
- 识别机会：新算子可能降低指定长序列场景的显存或计算成本，但收益范围尚未确认。
- 识别用户与任务：训练工程师需要在既定硬件预算内完成目标模型和序列长度训练，同时保持精度、稳定性和可恢复性。
- 量化现状差距：记录现有路径在目标模型、数据、精度和并行配置下的峰值、吞吐、失败比例和资源成本。
- 拆解需求：支持条件、正常路径、边界 Shape、fallback、API 兼容、误差、性能、观测和维护分别形成需求。
- 比较候选：维持现状、调参/切分、引入新算子并保留旧路径、全量替换等使用同一评价准则。
- 执行 PoC：只验证会改变决策的未知，例如 Shape 支持、端到端收益、精度边界和依赖成熟度。
- 评估工作量与价值：包括模型适配、框架接入、测试、兼容、CI、文档、运维和后续升级，而不只估算核心代码。
- 形成验收合同：阈值由需求责任人批准；PoC 数字只是阈值候选，不自动成为承诺。
一个最小需求片段如下：
| ID | 需求定义 | 优先级 | 开发前验收计划 |
|---|---|---|---|
UR-001 |
训练工程师应能在批准硬件预算内完成目标长序列任务 | Must | 目标模型、数据和并行配置的端到端演示 |
FR-001 |
满足支持条件时系统应使用候选路径，不满足时进入兼容路径 | Must | 正常、边界和不支持 Shape 场景测试 |
QR-001 |
吞吐、峰值显存和数值误差应满足批准阈值 | Must | 固定 baseline/candidate 条件的重复基准与误差评测 |
IR-001 |
公开 API、dtype/Shape 契约及错误语义应保持兼容 | Must | 接口审查、调用方回归和负例测试 |
CON-001 |
首版只支持批准模型、硬件和软件版本 | Must | 配置审查与能力探测测试 |
此时报告已经足以支持“是否立项、采用哪条路线、需要多少投入、怎样验收”，但没有声称任何正式实现已经完成。
固化为 Skill¶
仓库中的 $requirements-analysis Skill 将这套事前流程固化为中文工作流。即使输入包含已经穿刺的代码，它也只把代码当作技术调研证据，不在需求报告中输出完成状态。
最短调用方式是：
使用 $requirements-analysis，基于下面的客户诉求、现状材料、技术机会和可选代码证据，形成一份开发前视角的需求分析报告。
要求：
1. 识别客户真实需求，不把客户提出的功能或新技术直接当成需求；
2. 拆解业务、用户、功能、质量、接口和约束需求；
3. 调研候选技术方案，说明现有瓶颈、适用边界、PoC 和选择理由；
4. 评估技术/数据/资源/交付/运营/合规可行性、工作量区间和值不值得做；
5. 为每条 Must 需求定义可观察、可量化的验收条件；
6. 正文采用开发前语态，不写代码完成情况、测试结果或上线效果。
输入：
- 客户/用户诉求：<内容>
- 当前场景与问题材料：<内容>
- 技术机会或候选方案：<内容>
- 可参考的代码/实验：<可为空，只作为技术调研材料>
- 报告目标路径：<路径>
常见失败¶
- 把技术机会当需求：新模型、新算法、新算子只说明“可能做得到”，没有说明“谁值得为它投入”。
- 把客户方案当真实需求：客户说“加按钮、换模型、接算子”，分析者没有追问其任务、影响和成功结果。
- 从代码倒推需求正文：函数、模块和测试被直接翻译成需求编号，报告变成实现说明。
- 把完成情况写进需求：使用“已支持、已通过、已上线”，混淆需求合同与验收报告。
- 只有功能，没有质量和异常：性能、可靠性、兼容、观测、回退、维护和成本成为开发中的隐性争议。
- 先选方案再补价值：因为团队熟悉某技术就围绕它构造用户价值，形成循环论证。
- 只估核心编码：遗漏数据、测试、集成、迁移、运维、文档和跨团队依赖。
- 精确分数掩盖未知：基线、权重、置信度和工作量区间都不可靠，却输出精确 ROI 或优先级总分。
- PoC 即验收：探索环境中的一次成功被直接写成正式承诺。
- 验收词不可测：更快、更稳定、精度无损、易用等词没有场景、阈值和判定规则。
总结¶
需求分析报告的本质是在开发前降低决策不确定性。它先从客户和场景识别真实问题，再拆解需求，调研并比较技术路线，判断项目能否做、要花多少、是否值得，最后把需求冻结成可以验收的合同。
即使文档是在开发之后补写，也不应改变这项职责。现有代码可以帮助分析者看见技术事实，却不能成为正文的时间主线。报告应回答的是：如果现在还没有开始开发，我们凭什么决定做、决定做什么、选择哪条路线，以及未来怎样判定做对了。
参考资料¶
- ISO/IEC/IEEE 29148:2018 — Requirements engineering
- ISO/IEC 25010:2023 — Product quality model
- NASA Systems Engineering Handbook — System Design Processes
- CMU SEI — Architecture Tradeoff Analysis Method
- Cucumber Gherkin Reference