需求:REQ-{id}
Dispatch policy: waves-v1
名称:{需求名称} 状态:draft / locked / changed / archived (draft→locked 的翻转由 agent 依据人类在对话中的明确"锁定"拍板执行,见 skills: requirement-funnel) Owner:{产品/用户} PM / Architect:{姓名} 版本:v0.1.0 创建日期:YYYY-MM-DD UI impact:none / changed / unknown
<!-- 给 agent(固定阅读,2 行): 若预期效果可能改界面:先按 design-foundation 判定 local/core/extended;local 使用模块推导,core/extended 缺覆盖才走 F0–F6;再按 §A→§B→§C 推进。 提案纪律与自审见 requirement-funnel skill——上交唯一合格形态是完整方案,开放问题禁止上交。 -->
UI impact是状态:locked的强制顶部字段,req bind只解析这一处(§C 的回显必须与之一致,不一致会被拒绝)。值必须三选一:none/changed/unknown。unknown会触发规划暂停门禁,需在 §D 澄清后才能推进 S2。
§A 理念(Why)
A1 不是人的原话:你接收并理解人的表述后,过滤口语歧义、补全隐含前提,整理成结构化复述,交人确认"这就是我想说的"。原话会歧义;对话不入册,整理稿才是权威。
| 字段 | 内容 |
|---|---|
| A1 预期效果(agent 整理稿,人确认) | {做什么、为什么值得做——两三句} |
| A2 背景与痛点 | {问题和上下文}{现在没有它时用户怎么凑合} |
| A3 成功长什么样 | {完成后用户可感知的变化——验收的精神锚} |
| A4 明确不做(负空间/negative space) | {范围外事项——与 A1 同等重要,每条一句不做的原因;编号供 AC 指向列做 N/A 背书(§A4-2 即本表第 2 条)} |
用户和利益相关者(决策权"高"的诉求冲突 = 拍板点候选):
| 角色 | 诉求 | 决策权 |
|---|---|---|
| {角色} | {诉求} | 高 / 中 / 低 |
术语(分歧当场定名;统一叫法供全部下游文档使用):
| 术语 | 含义 | 禁止叫法 |
|---|---|---|
| {术语} | {含义} | {容易混淆的叫法} |
§B 方向与约束(How 的边界——需求级选型,架构归 S2)
方向取舍(每个被否方向必须有一句否决理由——ADR 雏形,S2 承接):
| 方向 | 一句话方案 | 采纳/否决 | 理由 |
|---|---|---|---|
| {方向 1(推荐标 ★)} | 采纳 | {为什么} | |
| {方向 2} | 否决 | {一句否决理由} |
硬约束(agent 对人给的每条"必须"追问打破的代价;答不出代价的不是必须,降级为偏好并入下方假设与风险表):
| 硬约束 | 为什么是必须 |
|---|---|
| {约束} | {代价/理由} |
关键假设与风险:
| 假设 / 风险 | 影响 | 缓解措施 / 验证方式 |
|---|---|---|
| {假设或风险} | 高 / 中 / 低 | {缓解或验证} |
§C 具体需求(What——逐条可追溯)
正向范围 = 本节需求点全集(FR + NFR);§A4 只登记负向。
需求点("服务于"指不回任何 §A 条目 = 范围蔓延,当场质疑):
| 编号 | 模块 / 流程 | 需求 | 服务于 §A_ | 优先级 |
|---|---|---|---|---|
| FR-001 | {模块} | {需求} | {A1/A2/…} | Must / Should / Could / Won't |
流程和异常:
| 流程 | 输入 | 输出 | 状态 | 异常 | 权限 | 验收标准 |
|---|---|---|---|---|---|---|
| {流程} | {输入} | {输出} | {状态} | {异常} | {谁能做/谁被拒} | {证据} |
验收标准(换个人来判,结果一样;指向列填写规则——S0 阶段只需保证 FR-{id} 指向 §C 真实存在的 FR 行;其余两种合法值是"经背书的 N/A":NFR-{id}(须在下方非功能需求表声明)或 §A4-{条目}(指向"明确不做"表的某一行)。自由文本(如"人工检查")会在 S2 收口时被机器拒绝。示例:FR-003 ✅ / NFR-002 ✅ / §A4-2 ✅ / 上线后观察 ❌):
| 编号 | 标准 | 指向 |
|---|---|---|
| AC-001 | {可判定的验收表述,含衡量指标} | FR-{id} / NFR-{id} / §A4-{条目编号} |
| AC-002 | 示例:提交成功后 3 秒内可见回执 | FR-003 |
| AC-003 | 示例:不承诺移动端适配 | §A4-2 |
非功能需求:
| 编号 | 类型 | 要求 | 验收标准 |
|---|---|---|---|
| NFR-001 | 性能 | {要求} | {指标} |
| NFR-002 | 安全 | {要求} | {证据} |
| NFR-003 | 可靠性 | {要求} | {证据} |
| NFR-004 | 合规 | {要求} | {依据} |
数据迁移范围清单(轻量模式、迁移类、重构类需求即使跳过独立设计文档也必须填写本区;本区是 task 拆分边界依据):
| 路径 / 文件 | 类型 | 处理动作 | 所属任务 | 引用 / 依赖 | 说明 |
|---|---|---|---|---|---|
{path} |
source / config / script / generated / test | migrate / keep / delete / review | TASK-{id} | {import/script} |
{说明} |
填写纪律:删除项在"说明"列注引用清理标准;每个文件映射到唯一 task 或明确标注共享边界;任务拆分前检查重复 import、脚本引用、生成物入口和别名路径。
UI 影响(任何涉及前端页面、组件、交互、可见状态、错误展示、权限展示或响应式布局变化的需求必须填写本区;UI impact = changed 时必须先完成 UI Design Package Gate 才能锁定 FE/BE/SYNC 合同):
| 字段 | 内容 |
|---|---|
| UI impact(引自顶部) | none / changed / unknown(顶部 blockquote 是唯一被 parseUIImpact 解析的位置,本节只回显,不独立声明) |
| 影响页面 / 模块 | {页面、路由、组件或 N/A} |
| Foundation reference | docs/design/DESIGN.md@vX.Y.Z / local / pending-foundation / N/A(none 可为 N/A;local 表示本 REQ 使用模块级推导,不发布项目级 Foundation;changed 的 Core/Extended 必须为版本化引用,不得用风格句替代。S1 parser 不读本字段,仍只解析顶部 UI impact) |
| Surface | SUR-0X@vX.Y.Z / local / N/A(Core/Extended 使用 SUR-*@version;local 仅用于模块级推导;旧值 consumer/operations 视为 SUR-01 别名) |
| Design posture | local / inherit / extend / exception(local 仅配合 local Foundation;extend 须在 Derivation Note 写清新增语法及是否候选晋升;exception 须同时有 docs/design/decisions/EX-*.md (legacy docs/design/exceptions/EX-*.md still recognized)) |
| Derivation note | docs/design/derivation/REQ-{id}.md / N/A(changed 时由 S2 填写且必须为可解析路径;local 亦需模块 Derivation;S0 可留 pending) |
| 模块当前真相包 | docs/design/prototypes/<module>/(index.html + stories.md + flows.md + scenario-model.json + cross-matrix.json + cases.json + scenario-coverage.json + fixture-contract.json + *.html)/ N/A |
| 原型门禁状态 | N/A / pending / ready |
真相包齐备性、S/F-NNN 完整性与 branch 覆盖率由 S2 的
loop-harness scenario validate校验,不在本节自查。
§D 待澄清问题
| 编号 | 问题 | 影响范围 | 阻塞范围? | 状态 | 结论 |
|---|---|---|---|---|---|
| Q-001 | {问题} | 范围 / 流程 / 状态 / API / 权限 / 验收 | 是 / 否 | open / closed | {结论} |
§E 锁定记录与逐层拍板(locked 行的拍板权在人;拍板行与自审由 agent 依拍板凭证填写)
| 日期 | 操作 | 操作人 | 说明 |
|---|---|---|---|
| YYYY-MM-DD | locked | {PM / Architect} | 用户确认范围;UI impact={none/changed/unknown} 已随顶部字段固化 |
逐层拍板记录(compaction 后的拍板凭证——对话不是权威,未落盘的拍板等于没发生):
| 层 | 日期 | 拍板人 | 方式 |
|---|---|---|---|
| §A | YYYY-MM-DD | {人} | 对话确认 |
| §B | YYYY-MM-DD | {人} | 对话确认 |
| §C | YYYY-MM-DD | {人} | 对话确认 |
{agent 自审结论——提议锁定前全审的输出,一段话:审过什么、修了什么、留了什么旁注}
§F 派生文档与覆盖矩阵(S0 不读不填——整个 §F 由 S3 起的 CONTRACTS-{id} 索引维护,本表仅锁定时快照;跳到 §G/文末即可)
<!-- 活矩阵唯一居所在 CONTRACTS-{id} 索引;REQ 是锁定基线,agent 不填写本表 -->派生 UI 设计包
| 模块原型集 | 路径 | 状态 | 覆盖需求 |
|---|---|---|---|
| <module> | docs/design/prototypes/<module>/ |
N/A / pending / ready | FR-{id} |
派生合同
| 合同 | 路径 | 状态 | 覆盖需求 |
|---|---|---|---|
| CONTRACTS-{id} | docs/dev/contracts/CONTRACTS-{id}.md |
draft / reviewed / locked | 当前 REQ 全量索引 |
| FE-{id} | docs/dev/contracts/FE-{id}.md |
draft / reviewed / locked | FR-{id} |
条款覆盖
| REQ 条款 / source_ref | Rule → CASE → Story → PATH → Spec | 合同条款 | TASK | 验证证据 | 状态 |
|---|---|---|---|---|---|
| REQ-{id}/FR-{id} | BR-{id} → CASE-{id} → S-{id} → F-{id} → PATH-{id} → web/e2e/{module}/*.spec.ts |
FE/BE/SYNC-{id} §{n} | TASK-{id} | REV/QA/E2E/BUG/ACC-{id} | planned / covered / verified |
模块当前真相映射
REQ 只能作为来源,不能创建需求私有设计或测试副本。任何触及模块的 REQ 都必须维护模块全集并触发 full-module regression。
| 模块 | Rule / CASE | Story | PATH | Spec | Round evidence |
|---|---|---|---|---|---|
| {module} | scenario-model.json / cases.json |
stories.md / S-{id} |
flows.md / F-{id} / PATH-{id} |
web/e2e/{module}/ |
REV/QA/E2E round {n} |
批次下游索引
| 关系 | 文档 | 路径 | 状态 |
|---|---|---|---|
| downstream | 任务看板 | docs/dev/tasks/index-REQ-{id}.md |
draft / executing / completed |
| evidence | Review round manifest | {team-manifest-path} |
pending / complete |
| evidence | Delivery verification | docs/reports/review/REV-{id}.md |
pending / PASS |
| evidence | QA evidence | docs/reports/qa/QA-{id}.md |
pending / PASS |
| evidence | E2E Tester evidence | docs/reports/e2e/E2E-{id}.md |
pending / PASS |
| evidence | Clean round | {review-evidence-path} |
pending / valid |
| evidence | 验收 | docs/reports/acceptance/ACC-{id}.md |
pending / passed |
| downstream | 发布审计 | docs/reports/release-audits/{file}.md |
pending / approved |
变更记录
| 日期 | 版本 | 变更内容 | 申请人 | 审批人 |
|---|---|---|---|---|
| 2026-08-15 | v2.0.0 | {示例行——首个真实变更从下一行开始} 重构为漏斗结构(§A 理念→§B 方向与约束→§C 具体需求→§D 澄清→§E 锁定→§F 覆盖矩阵);删除 PM Todo、21 项自查 checklist 与设计公理五问(实质分别转入字段/S2 引擎);状态枚举精简为 draft/locked/changed/archived;过程方法论由 requirement-funnel skill 承载;流程表补权限列、非功能表补 NFR 编号列 | owner | owner |