5.5 KiB
5.5 KiB
阶段 ① 需求与规格（Requirement & Spec）
定义：把用户意图变成一份"实现者（人或 agent）无需猜"的规格文档。规格完备的标志是：实现者不发明任何决策就能把改动做出来。 输入：需求描述 / issue / 用户反馈 / 变更请求。 输出：规格文档（按下方 7 段结构 + BR/E/AC 编号）。 进入下一阶段（② 架构设计）：六道完备性门全部通过。
1. 要求（Requirements）
1.1 进入条件
- 需求来源明确（谁提的、要解决什么问题、对哪些角色生效）。
- 明确本轮范围 vs 明确不在本轮范围（out-of-scope 与 in-scope 同等重要）。
- 单一交付面还是多交付面已确认（web / Electron 主进程 / 硬件网关 / 设置面板……每个交付面都会让规格多一段）。
1.2 完成条件（DoD）
- 七段结构齐全（多交付面则第 3 段重复），每个领域术语都进术语表
- 每条业务规则
BR-xx可测试（能说清"什么输入让它过、什么输入让它挂"） - 每条规则隐含的失败路径都有
E-xx，异常"用户可见消息 ↔ 后端错误码"绑定 - 每条
BR-xx/E-xx至少被一条AC-xx引用；验收含正常/异常/边界三类用例 - 无阻塞当前迭代的未决问题（或已把阻塞规则移出范围）
- 决策记录（Decision Record）已写明已定决策与被否掉的替代方案
2. 规则（Rules）
| 编号 | 规则 |
|---|---|
| R-1.1 | 行为必须有 id：业务规则 BR-01…，异常场景 E-01…，验收标准 AC-01…。散文式描述不能进入规格。 |
| R-1.2 | id 只追加不重排；规则废弃时标记 withdrawn 并保留编号（提交、测试、评审已引用旧 id）。编号按规格独立，不全局递增。 |
| R-1.3 | 每条 BR-* 只对应一个实现点。一条规则要碰三条无关代码路径 = 它其实是三条规则。 |
| R-1.4 | 每条 E-* 必须绑定"各受影响面展示给用户的消息"与"产生它的后端错误码"，前后端不能静默漂移。 |
| R-1.5 | 每条 AC-* 用 Given / When / Then 三元组，且引用它覆盖的 BR-*/E-* id。无验收引用的规则/异常 = 未验证，阻塞进入实现。 |
| R-1.6 | 未决定的事项显式标记（needs-decision / open question，带 owner 与期限），禁止用"貌似合理的编造值"填空。 |
| R-1.7 | 截图/线框图只表达布局，不替代规则：不得用截图当 spec，除非它同时写清状态转换与权限。 |
| R-1.8 | 反模式禁止：只写 happy path（§5/§6 才是实现风险所在）、把字段类型当业务规则（BR-* 描述系统要决定什么，不是存什么）、整段照抄他项目（可复用段清单，内容必须基于本目标事实重写）。 |
3. 输出规范
3.1 规格文档结构（7 段；每多一个交付面，第 3 段重复一次 → 8/9 段）
1. Requirement Overview 业务背景、in-scope / out-of-scope、受影响角色、术语表
2. Data Model & Interface 新增/变更的表（列类型、可空性）、服务契约、公开端点（请求/响应形状）、枚举、消息/事件载荷
Contract
3. Surface Specification 每个交付面：页面骨架、组件粒度、每个有状态视图的状态机、动作列表（含守卫权限）
4. Business Rules 编号 BR-01…，每条一条可测试语句
5. Exception Scenarios 编号 E-01…，触发条件 + 各面用户可见消息 + 后端错误码
6. Acceptance Criteria 编号 AC-01…，按角色分组，Given/When/Then，覆盖正常/异常/边界
7. Open Questions & 未决项（owner + needed-by）+ 已定决策与被否方案
Decision Record
参考模板：
vendor/better-harness/references/bootstrap/examples/frontend-web-spec.md（前端表面）、backend-service-spec.md（多交付面）、mobile-app-spec.md（离线/权限/版本）。复用结构，不复用表名/端点/阈值/角色名。
3.2 六道完备性门（任一不过，禁止进入实现）
| 门 | 判定 |
|---|---|
| Term gate 术语门 | 规则中每个领域术语都在术语表里 |
| Contract gate 契约门 | 表面展示/提交的每个字段都在 §2 里有类型，每个枚举值都列出 |
| Rule gate 规则门 | 每条 BR-* 可测试（评审者能说出"输入 X 通过、输入 Y 失败"） |
| Exception gate 异常门 | 每条规则隐含的失败路径都有 E-*；静默失败是规格缺陷，不是实现细节 |
| Coverage gate 覆盖门 | 每条 BR-*/E-* 至少被一条 AC-* 引用；验收含至少一个边界用例 |
| Decision gate 决策门 | 本轮范围内没有未决问题阻塞规则；要么移出范围，要么解决 |
3.3 交付物清单
- 规格文档（本地草稿放
docs/plans/，不入库，见.gitignore；需入库的规格随 PR 放docs/对应目录，命名<日期>-<主题>-spec.md） - （可选）给 UI 需求的面：指向 04-ui-spec.md 的表面规格拆分
4. 轻量路径（小改动）
- 一行修复 / 文案 / 纯内部重构：规格可缩为 PR 描述中的"范围 + BR/AC 各 1-3 条"，但 id 与可追溯要求不变。
- 无法写清验收标准的改动 = 规格未完成，不得进实现。
5. 相关文档
- 阶段 ② 02-architecture.md、阶段 ④ 04-ui-spec.md
- 规格→实现→验证的流程闭环定义见 README.md 全景