# 需求契约与模式路由规范

## 目录

1. 模式路由
2. 稳定 ID
3. EARS 契约
4. 正确性分析
5. 增量同步

## 1. 模式路由

先判断 `work_type=feature|bugfix`。Bugfix 读取 `Bugfix专用链路.md`；Feature 再选择：

| mode | 适用证据 | 必做 | 可省略 | 人工门禁 |
| :--- | :--- | :--- | :--- | :--- |
| `standard` | 陌生、复杂、高风险、多人协作 | 阶段 0-6 全部 | 无 | 阶段 0 回放、阶段 1 共识、阶段 2 价值、阶段 3 调研充分性、阶段 4.5 方案与 4.6 MVP 边界；阶段 5/6 不加形式化确认 |
| `quick` | 用户故事成熟、同类方案做过、风险低 | 阻塞问题前置、价值确认、MVP 边界、PRD、requirements、正确性分析、校验 | 深度调研、完整辩论、普通阶段确认可降级 | 阶段 1 共识、价值接受、MVP 边界；无法在 quick 内消解的 P0/P1 只升级受影响环节 |
| `tech-constrained` | 既有架构、严格延迟/吞吐/合规、迁移约束决定范围 | 先固化 NFR/禁改面，派 architect 做可行性证据，再锁需求 | 市场研究深度按项目需要 | 阶段 1 共识、价值接受、可行性冲突与 MVP 边界 |

用户未指定时推荐 `standard`。模式写入 `state.json.workflow_mode` 和 `requirements.md` 元数据。模式只改变普通阶段审批、研究深度和辩论强度；不降低阶段 1 收敛闸门、阶段 2 价值接受、阶段 4.6 MVP 边界，也不降低需求契约、正确性分析或校验门槛。升级只作用于证据不足或争议未解的环节，不把已通过部分整段重跑。

`tech-constrained` 在阶段 1 后、价值论证前增加可行性预检，输出 `evidence/technical-feasibility.md`：硬约束、现有系统证据、候选方案、不可行项、需要收缩的范围。没有代码/文档证据时只能标假设，不能宣称可行。

## 2. 稳定 ID

| 对象 | 格式 | 示例 |
| :--- | :--- | :--- |
| 功能 | `Fnn` | `F03` |
| 用户故事 | `US-Fnn-nn` | `US-F03-01` |
| 行为需求 | `REQ-Fnn-nn` | `REQ-F03-02` |
| 验收条件 | `AC-Fnn-nn` | `AC-F03-04` |
| 非功能需求 | `NFR-nnn` | `NFR-006` |
| 假设 | `A-nnn` | `A-014` |

规则：

1. 在场景锚点首次形成需求清单时分配；跨 PRD、requirements、设计、测试、任务原样传递。
2. 发布后永不重编号、复用或因排序改变；删除项保留并标 `retired`，替代项写 `supersedes`。
3. 一个 AC 只验证一个可观察结果，并且必须有 `Parent: REQ-*`。
4. 文案变化不换 ID；行为语义变化保留 ID 但递增 `revision`，拆分后旧 ID retired、新增 ID。
5. PRD 与 requirements ID/语义不一致时停止下游，先修单一事实源；不得让 design-master 猜。

### 2.1 关键决策与需求契约的边界

产品/架构决定只有通过 PRD 的三条件关键决策闸门，才写入 `PRD详细版.md` 一张简表并索引到 `state.json.key_decisions_made`；不创建独立 ADR/DR。若决定改变系统行为、阈值、兼容性或约束，必须同时落实为对应 `REQ/AC/NFR`，下游仍以这些稳定需求 ID 为事实源。

design-master 的 `DEC-nnn` 只用于没有直接 source ID 的设计层衍生决定，并写明必要性；不得拿 `DEC-nnn` 复制或替代 PRD 中的产品/架构决策记录。

## 3. EARS 契约

使用 `templates/requirements.md`。每个 AC 至少包含：

```text
WHEN <可观察的事件或条件>
THE SYSTEM SHALL <唯一、可验证的结果>
```

需要时使用 `WHILE <状态>`、`WHERE <可选能力>`、`IF <异常条件>` 补充前置语境，但最终必须有 `THE SYSTEM SHALL`。禁止“快速、友好、足够、大文件”等未量化词；把阈值、单位、时间窗、角色、数据范围写清。

每个 US 必须有 `Role`，并使用 PRD 角色矩阵中的稳定名称或已列别名。`External capability configuration` 表也必须保留：没有外部能力时只写 `none`；否则逐项写凭据归属、配置角色、配置入口、作用域、生命周期、所属阶段和对应需求，配置角色同样使用稳定角色名。`Surface` 只使用 `deployment-secret / onboarding / settings / admin / none`，`Scope` 只使用 `system / tenant / user / project / none`。`onboarding / settings / admin` 属于产品行为，必须关联至少一个真实 REQ；`deployment-secret` 只有在 PRD 已明确由内部技术人员统一部署时才可选，不能替代客户或用户自助配置。

`Capability prerequisites` 表同样必须保留：没有方案前置能力时只写 `none`；否则逐项记录状态、负责人、可核验证据或承诺截止时间、不可用时的替代方案、所属阶段和对应需求。`Status` 只使用 `ready / committed`：`ready` 必须给可核验证据，`committed` 必须给负责人和截止时间；当前不可用且没有可信承诺的能力不能伪装成前置条件已解决，依赖它的方案必须移出当前阶段或改选替代方案。认证通道、第三方平台登录、移动应用分发账号/签名、支付、推送、硬件或行业资质等一旦成为候选方案依赖，就必须先完成该表的事实确认，不能先定方案再补资源。

PRD 负责解释价值、场景与取舍；`requirements.md` 只保存下游必须实现和验证的行为，不复制研究过程。

## 4. 正确性分析

生成 `requirements-analysis.md`，按完整需求集合检查：

1. 逻辑不一致：两条单独合理、合在一起不可满足。
2. 含糊量词：会让两个实现者得到不同结果。
3. 约束冲突：功能、性能、安全、合规、成本无法同时满足。
4. 未声明假设：未定义角色、实体、状态、时间或外部系统。
5. 缺失路径：失败、边界、并发、重试、幂等、权限与恢复。
6. 不可验证指标：没有阈值、采样方式或时间窗。

固定结尾：

```text
P0 unresolved: 0
P1 unresolved: 0
```

每条发现列出涉及 ID、失败模式、建议修复和最终决议。P0/P1 未清零不得进入设计。

## 5. 增量同步

修改需求时输出影响集合：变更 ID、revision、直接依赖、下游需标 `stale` 的设计/测试/任务。只重生受影响项；未受影响 ID 与状态保持不变。已完成任务只有在映射的上游 revision 未变且 fresh regression 通过时才能继续保持 completed。