requirements-author

需求编写技能

概述

此技能定义如何在项目生命周期内编写和演进两类需求文档：业务需求文档（BRD）和产品需求文档（PRD）。通用的需求工程知识存放在 references/_shared/ 中，BRD 和 PRD 专属知识分别存放在 references/brd/ 和 references/prd/ 中，以便每个使用此技能的 Agent 只加载其文档所需的内容。

BRD 的标准模板是 brd-full.md，并配有 brd-frontmatter-overlay.md；PRD 的标准模板是 prd-full.md。BRD Builder 会分派到 BRD 阶段锚点（#discover、#define、#govern）；PRD Builder 会分派到 PRD 阶段锚点（从 #prd-assess 到 #prd-finalize）。

使用此技能时，请根据当前文档范围加载相应参考资料：

通用（references/_shared/）：

• 需求定义
• 可追溯性命名
• 可追溯性矩阵
• 需求研究集成

BRD 范围（references/brd/）：

• BRD 到 PRD 的交接
• 成果假设到 BRD 的交接
• BRD 质量格式

PRD 范围（references/prd/）：

• 产品探索
• EARS 验收
• PRD 质量格式

交接传递约定

产出方工作流负责每次交接的标准传递方式，消费方无论采用何种传递方式，都会验证完整负载。默认情况下，成果假设会以内联形式返回 OUTCOME_HYPOTHESIS_TO_BRD_HANDOFF_V1，因为它是基于已持久化源构件生成的一次性种子；用户也可以改为提供单独持久化的负载路径。BRD Govern 会持久化 BRD_TO_PRD_HANDOFF_V1 并返回其路径，因为该负载是跨 Agent 会话使用的持久治理记录。这种差异是有意为之，不会改变负载的权威性或验证方式。

BRD 生命周期

阶段	主要目标	进入条件	退出条件
Discover	确立业务背景、相关方范围和问题定义	请求或计划正在受理	Discover 硬性门槛通过，且构件完整
Define	编写完整、可测试且可追溯的需求内容	Discover 构件已获准进入详细编写阶段	Define 硬性门槛通过，并具备质量证据
Govern	在线性控制下定稿、批准并取代 BRD 版本	Define 交付包已获准进入治理审查	Govern 硬性门槛通过，且已记录发布构件

Discover {#discover}

活动

• 记录业务背景、驱动因素、强制约束和预期成果。
• 确定相关方、决策负责人和评审参与者。
• 明确范围边界、假设和依赖关系。
• 起草初始需求候选项，并映射早期可追溯性占位符。
• 验证并处理所提供的 OUTCOME_HYPOTHESIS_TO_BRD_HANDOFF_V1 负载。

成果假设接收

使用 成果假设到 BRD 的交接 作为规范契约。

1. 接受内联 YAML，或从用户提供的制品路径读取。
2. 在将任何值复制到 BRD 之前，验证完整载荷。
3. 拒绝不受支持的版本、不完整的种子、占位值和无效的来源信息。不得将被拒绝的载荷重新解释为非结构化证据。
4. 分配下一个稳定的 BG-### 标识符。
5. 分别记录陈述、KPI、基线、目标、时间范围、测量来源和负责人值。
6. 将每个种子字段标记为 accepted 或 revised。对于修订，保留源值、当前 BRD 值和理由。
7. 将假设和未解决问题映射到对应的规范 BRD 章节。除非 Discover 明确确认了其他由 BRD 管理的状态，否则将每个导入的问题初始化为 Open。每个延期问题都必须有延期理由，并指定一个目标阶段：PRD、Implementation、Operations 或 Future-Release。
8. 在 BRD 来源凭据中记录交接 ID、源路径、源文件 SHA-256 和 KPI 测量来源。

在 Discover 接受交接之前，经过验证的载荷是导入种子值的权威来源。Discover 可以明确接受或修订这些值。Discover 退出后，BRD 即为权威来源。后续的假设变更需要新的已验证载荷，并明确重新进入 Discover 阶段。

硬性退出门槛

仅当满足以下条件时，Discover 才可退出：

• 范围明确且有限，利益相关方的归属责任清晰。
• 核心假设和约束均已记录且可供审查。
• Define 所需的种子制品齐全且内部一致。
• 任何成果假设交接均已通过验证，每个导入的种子字段均有明确的处置结果，且来源凭据完整。

输出制品

• Discover 摘要和范围说明。
• 包含角色和归属关系映射的利益相关方清单。
• 初始假设和约束登记表。
• 用于 Define 的种子需求和可追溯性框架。
• 提供交接时生成的成果假设凭据和字段处置结果。

Define {#define}

活动

• 使用 brd-full.md 和规范命名规则编写完整 BRD 内容。
• 完善业务目标和需求集，明确验收意图。
• 构建并验证由作者维护的 FR、AC、BG 和 BR 记录之间的可追溯性链接。
• 根据 BRD 质量报告契约执行质量评估。

硬性退出门槛

仅当满足以下条件时，Define 才可退出：

• 需求内容完整、明确且可测试。
• 可追溯性链接符合当前有效的 ID 架构和命名策略。
• FR 到 AC 的覆盖率达到当前有效的 fr_to_ac_coverage_threshold_pct，或已记录阻碍项。
• 已生成质量问题，并依据既定标准完成审查。

输出制品

• 包含结构化章节的完整 BRD 草案包。
• 符合命名和 ID 约定、由作者维护的可追溯性矩阵。
• BRD 质量问题和汇总后的质量报告载荷。
• 包含审阅者备注的 Define 阶段门决策记录。

Govern {#govern}

活动

• 为最终审批准备 BRD，补充版本元数据和沿袭字段。
• 将获批的 BRD 从草案 0.x.y 版本升级至 1.0.0 或更高版本。
• 解决剩余的质量问题，或明确说明其处置结果。
• 发布获批的 BRD 输出和下游交接载荷。
• 发布替代版本时，维护版本替代链。

管控移交产出

在发出 BRD_TO_PRD_HANDOFF_V1 之前，BRD Builder 会应用 BRD-to-PRD Handoff 中的覆盖率和豁免验证规则，包括零 FR 覆盖率处理。它会从已签署的 BRD 和最终质量审查中记录以下值：

• 签署时 BRD 工件确切字节的 SHA-256 小写哈希值。
• 使用 id-schema.md 的 FR、NFR、BR、CON、AC 和 BG 标识符数量。
• 来自作者维护的可追溯性矩阵的 FR-to-AC 和 FR-to-BG 覆盖率指标。
• 最终 BRD_QUALITY_REPORT_V1 引用、整体状态和 Govern 决策。
• 签署审批人、角色、决策、审批时间戳、评论和有效豁免。
• 针对已接受的 FR-to-AC 阈值差距或 FR-to-BG 目标差距的豁免记录。

验证成功后，将完整 YAML 负载写入 .copilot-tracking/brd-sessions/<brd-name>.handoff.yml，在 BRD 会话状态中记录该路径，并返回该路径及简要的 Govern 摘要。不要依赖内联聊天负载作为下游传输方式。

硬性退出关卡

仅当满足以下条件时，Govern 才会退出：

• 已记录审批状态和必需的审阅者。
• 版本和沿袭元数据有效且完整。
• 最终质量报告授权退出 Govern。
• 已为下游使用方发布移交工件。

输出工件

• 已批准的 BRD 发布工件。
• BRD-to-PRD 移交负载。
• 包含审批证据的治理决策日志。
• 被替换 BRD 版本的取代关系链接记录。

状态分类

使用以下状态值跟踪 BRD 生命周期：

• draft：正在撰写或修订。
• in-review：正在进行正式审查和关卡验证。
• approved：已获准用于受治理的用途。
• superseded：已被更新的已批准 BRD 取代。

质量量规指引

将 BRD Quality Formats 中的 BRD 质量量规和负载契约与 Requirements Definition 中的指南结合使用。将量规结果作为 Define 和 Govern 决策的关卡证据。BRD Quality Reviewer 会生成标准发现项和汇总质量报告。

取代关系沿袭规则

• 合并范围时，一个 BRD 可以取代一个或多个较早的 BRD。
• 一个 BRD 只能由一个已批准的后继版本取代。
• 每次取代事件都会记录 supersedes 和 superseded_by 链接。
• 取代关系会保留历史工件，以便审计。

PRD 生命周期

PRD Builder Agent 会运行七阶段生命周期。每个阶段在下方都有自己的章节锚点，以便 Agent 仅加载当前阶段的指南。

阶段	章节锚点	主要目标
评估	#prd-assess	确定是否已有足够上下文来创建 PRD 文件。
探索	#prd-discover	确定 PRD 标题、范围和产品目标。
创建	#prd-create	上下文明确后生成 PRD 文件和状态文件。
构建	#prd-build	迭代收集详细需求。
集成	#prd-integrate	纳入参考资料、文档和外部材料。
验证	#prd-validate	在批准前确保完整性和质量。
定稿	#prd-finalize	交付完整且可执行的 PRD。

PRD 评估 {#prd-assess}

评估

• 判断是否有足够的产品背景信息来创建 PRD 成果。
• 明确计划、问题陈述和主要目标用户。
• 检查是否存在上游 BRD_TO_PRD_HANDOFF_V1 成果路径；若存在，则读取其覆盖范围和豁免背景。
• 检查是否存在上游可行性到 PRD 的交接。按照 可行性到 PRD 交接 根据 kind 识别交接，验证必需的元数据、裁决字段是否存在，以及工作区相对研究路径是否可读。将可行性作为补充证据，并保留已批准的 BRD 范围。
• 对于新会话，在评估输出中保留交接类型、路径、摄取时间戳、裁决和研究修订标识符，直到创建阶段写入状态文件。若状态已存在，则直接更新其中的可行性交接元数据对象。在交接成果中保留原始候选内容。
• 决定是收集更多背景信息，还是继续创建文件。

硬性退出条件

仅当满足以下条件时，评估阶段才可退出：

• 能够得出有意义的 kebab-case PRD 名称。
• 已明确问题定义和主要用户。
• 已读取任何可用的 BRD 交接成果、验证其有效负载并记录其覆盖指标。
• 任何可用的可行性交接均已通过 kind 识别，包含可读的工作区相对路径、有效的裁决格式，以及已为创建阶段准备好或已保存在现有状态中的规范化元数据。

输出成果

• 评估摘要，说明背景信息是否充分。
• 推导出的 PRD 工作标题。
• 存在 BRD 交接有效负载时，摄取的交接背景信息。
• 存在可行性交接时，提供可行性裁决、证据摘要、约束、差距和规范化交接元数据。否定裁决不会创建候选项处置结果。

PRD 发现 {#prd-discover}

活动

• 通过有针对性的问题明确 PRD 标题、范围和产品目标。
• 使用 产品探索 和 MVP 界定 探索问题空间。
• 使用 指标框架记录目标用户、候选成功指标和明确的非目标。

硬性退出条件

仅当满足以下条件时，发现阶段才可退出：

• 标题和范围明确。
• 已列出主要用户和候选成功指标。
• 已记录范围内和范围外的边界。

输出成果

• 发现摘要。
• 范围和非目标说明。
• 候选成功指标。

PRD 创建 {#prd-create}

活动

• 从 prd-full.md 生成 PRD 文件，并在标题和背景信息明确后创建会话状态文件。
• 根据已确定的范围、用户和目标填充骨架。
• 为构建阶段预先设置迭代式需求和指标结构。
• 如果评估阶段生成了规范化的可行性元数据，则将其字段作为 feasibilityHandoff 原子性地写入新状态文件，并保留 kind、path、ingestedAt、verdict 和 studyRevisionId。在此约定之前写入的状态可能包含 schemaVersion 而非 kind；读取时不得报错，并在下一次更新可行性元数据时将该对象重写为当前格式。不得持久化原始候选内容。

硬性退出条件

仅当满足以下条件时，创建阶段才可退出：

• PRD 文件和状态文件均已存在。
• 骨架符合规范的 PRD 结构。
• 已预先填入初始范围和目标。
• 评估阶段提供的任何规范化可行性元数据，均已在构建阶段开始前写入新创建的状态文件。

输出成果

• PRD 草稿骨架。
• PRD 会话状态文件。
• 已填入内容的范围和目标章节。
• 提供可行性交接元数据时，已将其持久化。

PRD 构建 {#prd-build}

活动

• 迭代收集详细的功能和非功能需求。
• 存在 feasibilityHandoff 时，从其相对于工作区的路径读取候选内容。如果已报告摄取内容但元数据缺失，或路径无法读取，则停止。
• 为每个正向判定的可行性候选项分配且仅分配一个由 PRD 管理的处置结果：accepted-fr、accepted-nfr、accepted-constraint、retained-gap、rejected 或 deferred。仅将关注提示视为参考证据。
• 仅在编写并接受 PRD 陈述后，才分配最终的 FR-###、NFR-### 或 CON-### 标识符。在 Feasibility Candidate Disposition 登记表中保留来源移交 ID、来源候选项 ID、证据引用、处置结果、理由和最终 PRD ID。
• 保留已签署 BRD 的权威性。记录并明确解决 BRD 与可行性之间的冲突；如果现有证据不足以支持负责任的解决方案，则将其保留为 Build 缺口。
• 使用 EARS Acceptance 和 Connextra Template 编写验收标准。
• 使用 NIST 800-160 NFR taxonomy 对非功能需求进行分类，并依据 INVEST 检查用户故事。
• 使用 Traceability Naming、Traceability Matrix 和 id-schema.md，维护需求、目标和指标之间的作者可追溯性。

硬性退出门槛

仅在以下条件全部满足时，Build 才可退出：

• 需求完整、可测试且可追溯。
• 验收标准采用 EARS 或 Given-When-Then 格式。
• 非功能需求已分类。
• 覆盖率达到当前阈值，或已记录阻塞项。
• 每个正向判定的可行性候选项都恰有一条处置记录，每条已接受记录都注明最终 PRD ID，且负向判定没有候选项记录。

输出产物

• 完整的 PRD 需求集。
• 作者维护的可追溯性矩阵。
• 验收标准和 NFR 分类。
• 存在正向可行性移交时，提供 Feasibility Candidate Disposition 登记表。

PRD 集成 {#prd-integrate}

活动

• 纳入用户提供的参考资料、文档和外部材料。
• 将传入内容与现有需求进行协调并解决冲突。
• 将支持性证据关联到需求和指标。

硬性退出门槛

仅在以下条件全部满足时，Integrate 才可退出：

• 已纳入提供的参考资料，或已明确将其延期处理。
• 已解决来源之间的冲突。
• 已关联支持性证据。

输出产物

• 已整合参考资料的 PRD 更新章节。
• 参考资料和证据关联记录。

PRD 验证 {#prd-validate}

活动

• 在批准前评估完整性和质量。
• 按照 PRD Quality Formats，运行 PRD Quality Reviewer 以生成 PRD_STANDARD_FINDINGS_V1 和 PRD_QUALITY_REPORT_V1。
• 根据评审标准审查发现，并解决缺口或记录其处置方式。

硬性退出门槛

仅在以下条件全部满足时，Validate 才可退出：

• 已生成质量发现和汇总报告。
• 报告通过 gate_decisions.validate_exit 授权退出 Validate。
• 覆盖率和质量阈值已达到或已获豁免。

输出产物

• PRD 质量发现和报告负载。
• Validate 门槛决策记录。

PRD 定稿 {#prd-finalize}

活动

• 交付完整且可执行的 PRD。
• 解决剩余发现，并记录版本和审批元数据。
• 运行 Finalize 偏差检查并发布下游产物。

硬性退出门槛

仅在以下条件全部满足时，Finalize 才可退出：

• 已记录审批状态和必需的评审人员。
• 最终质量报告通过 gate_decisions.finalize_exit 授权退出 Finalize。
• 不存在尚未解决的阻塞性发现。

输出产物

• 已批准的 PRD 发布产物。
• 完成决策日志，并附上批准证据。

参考资料

此技能将参考文档归入 references/，分为三个范围：references/_shared/ 中共享的需求工程知识、references/brd/ 中 BRD 专属知识，以及 references/prd/ 中 PRD 专属知识。仅在阶段活动需要时加载参考文档正文；每份正文都会链接到其子参考资料（标准指引、评分表和示例）。

共享参考资料（references/_shared/）

• requirements-definition.md - 需求类别、规范陈述形式、验收标准格式和质量维度。
• stakeholder-analysis.md - Mendelow 权力/利益矩阵和 RACI 责任变体。
• process-modeling.md - 可选的流程、决策和结构图指南。
• prioritization-schemes.md - 必须采用的 MoSCoW 优先级方案。
• traceability-naming.md - 需求、目标和决策标识符的路由及可追溯性约定。
• id-schema.md - 规范前缀、位数及相邻标识符规则。
• traceability-matrix.md - 由作者维护的 FR-to-AC、FR-to-BG 和 BR-to-FR 矩阵视图。
• design-decisions.md - DD-### 设计决策代码注册表。
• quality-rubric.md - 操作状态分类法（RISK / CAUTION / COVERED / NOT_APPLICABLE）和门禁决策规则。
• standards-excerpts.md - 按名称引用的第三方标准（ISO、IIBA、PMI、ISTQB）仅引述注册表。

BRD 参考资料（references/brd/）

• brd-quality-formats.md - BRD 数据契约的生产者与使用者映射。
• requirements-quality-rubric.md - 综合评分表，涵盖逐项需求、逐个 NFR 类别和逐个业务目标。
• handoff-payload-schema.md - BRD 作者视角下的 BRD 到 PRD 移交载荷。

PRD 参考资料（references/prd/）

• product-discovery.md - PRD 范围的问题空间探索与发现式提问。
• mvp-framing.md - MVP 界定和范围边界指南。
• metrics-frameworks.md - JTBD、HEART 和 AARRR 成功指标框架。
• ears-acceptance.md - PRD 需求的 EARS 验收标准模式。
• nist-800-160-nfr.md - NIST 800-160 非功能需求分类法。
• invest.md - 用户故事的 INVEST 质量标准。
• connextra-template.md - Connextra 用户故事模板。
• prd-quality-formats.md - PRD 数据契约的生产者与使用者映射。
• feasibility-to-prd-handoff.md - 有关可行性评估的使用规则，涵盖导入、创建持久化、构建处置、BRD 共存及来源可追溯性。

模板

templates/ 下的模板根据文档 frontmatter 和规范文档结构进行选择。

• brd-full.md - 标准 BRD 模板，涵盖从执行摘要到签署确认的所有章节。
• brd-frontmatter-overlay.md - BRD YAML frontmatter 的架构，包括 diagram_format、沿袭关系、覆盖率阈值和需求前缀覆盖项。
• diagram-mermaid.md - Mermaid 流程图片段；默认图表格式。
• diagram-ascii.md - ASCII 流程图片段，用于 Discover 阶段的低保真草图。
• prd-full.md - 标准 PRD 模板，涵盖从产品概览到验收和指标的所有章节。

数据契约

有效载荷契约用于管理每种文档类型的质量评估和下游交接。质量和 BRD 交接有效载荷携带固定的 schema_version；使用方遇到任何其他值时都会立即失败，因此这些常量绝不能更改。可行性到 PRD 的交接则携带普通的 kind 标记，因为其生产方和使用方会一起发布，无需进行版本协商。

BRD 数据契约：

契约	schema_version	参考文档
标准发现项	BRD_STANDARD_FINDINGS_V1	brd-standard-findings-v1.md
质量报告	BRD_QUALITY_REPORT_V1	brd-quality-report-v1.md
BRD 到 PRD 的交接	BRD_TO_PRD_HANDOFF_V1	brd-to-prd-handoff-v1.md

PRD 数据契约：

契约	schema_version	参考文档
标准发现项	PRD_STANDARD_FINDINGS_V1	prd-standard-findings-v1.md
质量报告	PRD_QUALITY_REPORT_V1	prd-quality-report-v1.md

上游 PRD 输入契约：

契约	标识符	参考文档
BRD 到 PRD 的交接	schema_version: BRD_TO_PRD_HANDOFF_V1	brd-to-prd-handoff-v1.md
可行性到 PRD 的交接	kind: feasibility-to-prd-handoff	feasibility-to-prd-handoff.md

PRD 生命周期在 Assess 阶段会使用这两种上游契约。BRD 输入提供已批准的业务背景、覆盖率和豁免项。可行性输入则为 PRD Build 提供已确认的结论、证据、约束、缺口和候选提案。两种契约都不能绕过 PRD 编写流程。

强制加载指令

BRD Builder 和 PRD Builder Agent 各自执行阶段 → 章节加载约定。每个阶段在执行阶段工作前，MUST 加载此技能的对应章节，并 MUST 将章节锚点追加到 state.phaseSkillsLoaded。

BRD Builder 指令：

阶段	章节锚点	必需的 phaseSkillsLoaded 条目
发现	#discover	brd-author#discover
定义	#define	brd-author#define
治理	#govern	brd-author#govern

PRD Builder 指令：

阶段	章节锚点	必需的 phaseSkillsLoaded 条目
评估	#prd-assess	prd-author#assess
发现	#prd-discover	prd-author#discover
创建	#prd-create	prd-author#create
构建	#prd-build	prd-author#build
集成	#prd-integrate	prd-author#integrate
验证	#prd-validate	prd-author#validate
定稿	#prd-finalize	prd-author#finalize

Agent 使用 read_file 读取此技能文件中的章节，并在执行任何阶段工作之前，将条目记录到 state.phaseSkillsLoaded。phaseSkillsLoaded 是持久的加载历史记录，并不能证明当前模型上下文中包含相关指南。在同一活动上下文中，重新进入已读取过对应章节的阶段时，无需重新加载。冷启动、恢复或上下文摘要之后，即使已记录相应条目，Agent 也会重新加载当前阶段的章节。

来源归属

随附的参考正文仅通过名称和条款引用第三方标准和框架；未复现或转述任何上游内容。参考资料提及标准的特征或类别时，随附的审查标准、锚点和指标均为 Microsoft 根据 CC BY 4.0 发布的原创内容，并非对标准定义的复现；权威定义见所引用的标准。standards-excerpts.md 中仅供引用的注册表是新增标准引用的唯一位置。按名称引用的标准包括 ISO/IEC/IEEE 29148:2018、ISO/IEC 25010:2023、IIBA BABOK v3、PMI Business Analysis for Practitioners、ISTQB Glossary、OMG BPMN / DMN / UML、Cucumber Gherkin pattern 和 MoSCoW prioritization；各自均为相应权利持有者的财产。

许可

此技能为 Microsoft 原创内容，采用 CC BY 4.0 许可。