规约驱动工作流

要解决的工程问题

很多团队不是“没有规范”，而是规范没有生效。需求在评审前就被写成代码，验收标准说“体验要友好”“响应要快”，却无法测试；实现过程中遇到边界情况靠临场判断，最后联调才发现错误路径没人定义。结果是返工、争论“是否完成”，以及大量无法追溯的代码。

spec-driven-workflow 把规范当作合同，而不是事后文档：每一行实现都要能回溯到 FR-* 或 NFR-*，每一条验收标准都要能生成测试。

技能如何工作

• 采用固定规范结构：标题元数据、上下文、功能需求、非功能需求、验收标准、边界用例、API Contracts、数据模型、范围外事项，缺项也要写明 N/A — [reason]。
• 需求使用 RFC 2119 关键词：MUST、MUST NOT、SHOULD、MAY，避免“应该尽量”这类不可执行表述。
• 通过有界自主规则决定何时停止：发现范围蔓延、歧义超过 30%、需要破坏性变更、涉及安全或无法保证性能指标时必须升级，并给出建议项而不是开放式提问。
• 六阶段流程把规范变成可执行证据：收集需求 → 写规范 → 校验规范 → 生成测试桩 → 按 AC 实现 → 自审；最后核对每个 AC-* / EC-* 都有通过的测试，且没有范围外实现。
• 与 TDD 的分工明确：规范回答“测什么”，TDD 回答“怎么实现”。

适用边界与注意点

• 规范本身有维护成本。如果需求变化很快却仍要每次评审后才能实现，流程可能成为瓶颈；更适合缺陷成本高于评审成本的系统、API、迁移和跨团队协作。
• 规范不是详细设计。它应约束行为、接口、数据模型和可测试阈值，但不应过度规定内部实现，否则会把不必要的细节固化下来。
• AI Agent 使用时要把 STOP 规则视为硬约束。尤其涉及认证、授权、加密、PII、数据库 schema 或公共接口变更时，不能自行猜测实现。
• 验收标准必须是机器可验证的。像“体验好”“性能优秀”这类表述需要改写成明确输入、预期结果、状态码、延迟阈值或错误响应。
• 写完后规范不要当成终点。代码、测试、接口契约和数据库约束都要能在自审清单中逐项对上，否则说明规范还没有真正生效。