规格驱动开发门控工作流
规格驱动开发门控工作流
学习目标
- 理解四阶段门控工作流与苏格拉底需求收敛的关系
- 掌握规格六大核心区域的编写要求
- 学会应用边界三层系统（Always / Ask First / Never）
- 掌握成功标准重构法（将模糊需求转化为可测试条件）
前置知识
本章涉及编码前门控的通用原理，建议先阅读：
下文直接聚焦 agent-skills 的具体实现。
项目实践
四阶段门控工作流
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT │ │ │ │ ▼ ▼ ▼ ▼ Human Human Human Human reviews reviews reviews reviews每个阶段必须通过人工验证后才进入下一阶段。这不是建议——在 spec-driven-development 技能中，这是 Hard-Gate。
规格六大核心区域
规格文档必须覆盖以下六个区域：
| # | 区域 | 要求 | 示例 |
|---|---|---|---|
| 1 | Objective | 构建什么、为什么、用户是谁、成功的样子 | ”作为用户，我可以创建任务” |
| 2 | Commands | 完整的可执行命令（含标志） | npm test -- --coverage |
| 3 | Project Structure | 源码、测试、文档的目录布局 | src/ → 应用源码 |
| 4 | Code Style | 用一个真实代码片段展示风格 | 不是三段描述，是一个代码示例 |
| 5 | Testing Strategy | 框架、测试位置、覆盖率期望 | Jest, tests/ 目录 |
| 6 | Boundaries | Always / Ask First / Never | 提交前运行测试 |
Code Style 的关键设计：agent-skills 强调”一个真实代码片段胜过三段描述”。这是因为 Agent 更擅长模仿模式而非遵循抽象描述。
边界三层系统（Boundaries Three-Tier）
| 层级 | 含义 | 示例 |
|---|---|---|
| Always | 无条件执行 | 提交前运行测试、遵循命名约定、验证输入 |
| Ask First | 需要人工确认 | 数据库 schema 变更、添加依赖、修改 CI 配置 |
| Never | 绝对禁止 | 提交密钥、编辑 vendor 目录、未经批准删除失败测试 |
为什么需要三层：Agent 需要在两个极端之间有指导——既不是”所有决策都自己判断”（可能导致灾难），也不是”每个决策都问”（效率太低）。三层系统提供了一个实用的中间地带。
成功标准重构法
将模糊需求转化为可测试条件的模式：
需求："让仪表盘更快"
重构后的成功标准：- 仪表盘 LCP < 2.5s（4G 连接）- 初始数据加载 < 500ms- 加载期间无布局偏移（CLS < 0.1）→ 这些是正确的目标吗？为什么有效：这使得”完成”的定义变得可测试。没有可测试的标准，Agent 可能永远不知道何时停止优化，或者在错误方向上走太远。
规格是活文档
agent-skills 将规格视为活文档：
- 决策变更时：先更新规格，再实现
- 范围变更时：新增或裁剪的功能反映到规格中
- 提交规格：规格与代码一起在版本控制中
- 在 PR 中引用：每个 PR 链接回其实现的规格部分
与苏格拉底七步流程的关系
苏格拉底七步流程（需求发现） ↓四阶段门控（SPECIFY → PLAN → TASKS → IMPLEMENT） ↓增量实现 + TDD苏格拉底流程关注需求发现（一次一问、方案对比、分段审批），四阶段门控关注需求发现后的执行链路。两者的配合确保从模糊想法到可交付代码的完整路径都有门控保护。
问题与规避
| 陷阱 | 表现 | 对策 |
|---|---|---|
| ”规格会拖慢速度” | 跳过规格直接写代码 | 15 分钟规格防止数小时重做 |
| 规格过长 | 规格变成完整设计文档 | 规格是起点，不是完整设计 |
| 边界定义模糊 | ” Ask First” 太多或太少 | 根据项目经验调整，初始保守 |
| 成功标准不可测试 | ”用户体验良好” | 转化为具体指标（LCP、延迟、错误率） |
设计取舍
为什么规格必须包含 Commands 区域？
Commands 是”可执行的知识”。Agent 需要知道完整的命令（含标志），而不是工具名。npm test 和 npm test -- --coverage 是不同的——前者可能遗漏覆盖率报告。Commands 区域确保 Agent 不会发明不存在的命令或遗漏关键标志。
为什么”一次全做更快”是反合理化？
感觉更快，直到某处坏了而你找不到 500 行变更中哪行导致的。门控的价值在于每一步的人工检查点——这些检查点捕获方向性错误，而在方向错误已经积累大量代码后再发现，代价是几何级增长的。
参考来源
- 源码验证:
skills/spec-driven-development/SKILL.md— 完整的四阶段工作流 - 源码验证:
skills/incremental-implementation/SKILL.md— IMPLEMENT 阶段的具体执行方式