产品需求文档（PRD）标准

本标准定义 AutoDev Platform Feature 的产品需求基线。PRD 是产品问题、范围、行为和验收结果的权威入口，不是工程资料汇编，也不等同于 Development、Verification 或 Release Ready。

适用对象

每个 Feature 只有一个 canonical 入口：docs/capabilities/<domain>/<feature>/index.md。
进入正式 PRD 编写后，入口声明 doc_type: prd；尚未形成需求基线的 Feature 保持 feature 或 stub，不得用空章节伪装完成度。
Automation PRD 是 integration-runtime 类型的合格示例，不是所有 Feature 必须逐节复制的固定模板。

PRD 与关联文档的边界

PRD 必须回答“为什么做、给谁做、做什么、不做什么、用户得到什么结果、如何判定满足需求”。以下内容不属于 PRD 正文，应由关联文档拥有并从 PRD 引用：

内容	Owning surface
原子 Requirement、Acceptance Criterion 与永久资产关系	需求与验收清单
页面状态、交互细节与原型	用户体验文档
算法、协议、Schema、并发、事务和故障机制	设计与工程合同
Code Map、仓库、文件、symbol 和实施任务	Code Map / Work Package
fixture、测试步骤、执行结果和环境证据	测试规格及 owning evidence
部署命令、恢复步骤和一次性运行事实	发布文档 / Runbook / owning runtime

PRD 中禁止放置手工维护的工程就绪卡片。Development、Verification 和 Release Ready 只能由资产关系与正式证据派生。

最小内容合同

draft 和 approved PRD 都应覆盖下列语义。标题可以包含章节号，但不得通过改名隐藏缺失内容。

文档信息与变更记录。
背景、用户问题、产品目标和成功指标。
目标用户、用户故事和核心场景。
本期范围、后续范围以及明确不做或非目标。
带稳定 FR-NNN 编号的功能需求。
权限和跨功能业务规则。
性能、安全、兼容、可用性等非功能要求。
数据、埋点或“不需要采集”的明确结论。
整体验收标准。
发布计划、依赖、风险和待确认事项。
关联产品、设计、验收和工程资料。

每个进入本期范围的功能需求必须说明用户故事、适用条件、产品行为、异常与边界以及 Given / When / Then 验收标准。这些语义可以分别使用“前置条件 / 主流程 / 异常与边界”，也可以由“页面必须展示 / 业务规则”等适合该功能的结构表达；不能只写用户故事和验收示例而省略规范行为。验收文本不得再引用未定义的“既定规则” “约定时间”或“用户可接受时间”。

Profile 条件合同

Profile	在最小合同之外需要补充
`standard`	与该业务实际相关的规则、数据和验证
`experience`	用户旅程、关键页面、空态、错误态、加载态、权限态和可访问性
`integration-runtime`	外部依赖、身份权限、幂等、超时、状态收敛、兼容与故障边界
`delivery-active`	灰度、兼容、迁移、回滚和发布门
`stub`	已知目标、未知项、补全条件和下一责任人；不创建空 PRD

不存在的职责无需为满足模板而硬增内容；需要作出“不适用”结论时，必须说明原因和判定人。

成功指标合同

每项用于验收或发布的指标必须同时给出：

指标名称；
当前基线（本次改动生效前的实测值，并注明取值时点）；
分子、分母或起止事件等计算口径；
数值目标；
观察窗口；
时钟或事实来源；
对结果有实质影响时的环境、负载及有效/无效样本边界。

当前基线是硬要求，不得省略。 只有目标值、没有基线的指标无法回答"改完之后算不算达成"：没有起点就没有增量，也无法分辨观测到的变化是本次改动带来的还是原本就在发生。首次建立指标、确实尚无历史数据时，必须写明"无历史数据"并给出本次测量即作为基线的结论与取值时点—— "未采集""暂缺"不构成结论。

“优化”“尽快”“友好”可以描述方向，但不能单独构成规范性要求或验收标准。

追踪合同

FR-NNN 在同一 Feature 内永久唯一，不因章节移动而重排。
每个进入本期范围的 FR 必须映射至少一个成功指标。 映射不出成功指标的 FR 说明它服务的问题尚未说清，必须交回产品决策，不得直接进入实现——否则就会出现"功能都做完了，但没人说得清它解决了什么问题"。
每个本期 P0 FR 必须映射至少一个 Requirement、Acceptance Criterion 和测试规格。
experience 与 integration-runtime Profile 的 P0 FR 还必须映射 UI 或 FLOW 用户场景。
PRD 只展示追踪概要；原子合同与测试步骤由关联文档拥有，避免两套规范性正文。
需求改变时，同一 MR 必须同步修改受影响的追踪关系；只改 PRD 或只改附件均不构成一致基线。

文档状态门禁

状态	判定
`stub`	产品问题或边界尚未建立，不是可评审 PRD
`draft`	可以存在未知项；每项必须声明决策人、最迟阶段和阻塞影响；没有未知项时明确写“无”
`approved`	本期范围、P0 行为、验收和成功指标已经确定，且不存在阻塞开发或验收的产品决策
`deprecated`	已被替代或退出使用，并保留历史可追溯性

格式检查通过不会自动把文档升级为 approved。产品行为由 Producer 批准；QA owner 判断验收是否可执行；设计、安全和数据 owner 按 Profile 与风险参与评审。实现者不能替代这些角色补做产品决策。

自动检查与人工评审

CI 通过 scripts/prd_contract.py 检查 canonical 位置、frontmatter、必需章节、FR 唯一性、P0 追踪、成功指标基本口径、模糊规范用语和 PRD/工程边界。Feature 专用测试继续保护具体产品语义与跨文档一致性。

现状（2026-09-20）：scripts/prd_contract.py 已在 d55a8b（"Remove non-contract tests"）中随若干非契约测试一并移出 master，本条所述自动检查当前未在运行；本节的成功指标合同与追踪合同仍按上文执行，但由人评审把关。同一批规则已在 DSH 侧实现为只读工具 sdoc_prd （@autoai/software-doc-usage），它比本标准的 13 章结构更严——额外强制"当前基线"与"全量 story → 成功指标追溯"，并把这些规则做成可机器判定的检查。恢复 docs 仓侧自动检查或长期由 sdoc_prd 承担，是需要单独决定的事。

自动检查不判断业务取舍是否正确。评审人仍须核对反例、权限、状态转换、失败处理、指标可实现性，以及 PRD 与交互、设计和测试文档是否表达同一个产品行为。

变更规则

影响范围、用户行为、业务规则、指标或验收结果的修改必须提升 document_version 并更新变更记录。
纯错别字、链接或排版修复可以不提升产品版本，但不得借此改变规范含义。
PRD、产品生命周期、工程 readiness 和实际执行状态是四种不同事实，不得合并为一个状态字段。

适用对象​

PRD 与关联文档的边界​

最小内容合同​

Profile 条件合同​

成功指标合同​

追踪合同​

文档状态门禁​

自动检查与人工评审​

变更规则​

相关资料​