【AI coding 智能体设计系列-07】规约驱动：让交付可复现的Spec工作流

声明：本文为学习笔记与工程化延伸，核心脉络来自阿里云开发者技术号发布的《AI coding 智能体设计》，在此基础上按"可落地教程"的方式重组，并给出最小 Spec 工作流模板；如有出入，以原文与官方文档为准。原文链接见文末参考。

用 AI coding 最容易掉进的坑，不是写不出来，而是对齐不可复现：

今天聊出来的约束，过两天找不到
同一句需求，跑两次结果完全不同
代码改完了才发现"验收标准根本没对齐"

《AI coding 智能体设计》提到 OpenSpec/规约驱动开发（spec-driven development）的思路：

在 AI coding 时代，规约、提示词、任务清单可能比代码更像"核心资产"，应该留在仓库里，而不是散落在聊天记录里。

这篇给你一套"最小可落地"的 Spec 工作流。

01｜最小目录：先把"合同"放进仓库

你不需要一上来就引入复杂体系，先从一个最小结构开始：

text 复制代码

changes/<id>/
  proposal.md   # 背景/范围/验收标准
  design.md     # 关键决策与取舍（可选）
  tasks.md      # 可勾选执行清单（必须）

这三个文件的角色分别是：

proposal.md：回答"为什么做""做到什么程度算完成"
design.md：回答"关键取舍是什么""为什么这么选"（可选但很值）
tasks.md：回答"具体要做哪些可验证的事情"

02｜proposal.md 模板（可直接复制）

md 复制代码

## 背景
- 问题现象：
- 影响范围：

## 目标（Goals）
- [ ] ...

## 非目标（Non-goals）
- [ ] ...

## 验收标准（Acceptance Criteria）
- [ ] 功能层面：...
- [ ] 质量层面：测试/性能/安全/文档 ...

## 约束（Constraints）
- 不改 public API
- 改动最小
- 必须给验证步骤

写 proposal 的关键不是写得长，而是把边界写清楚：

你不写边界，智能体就会帮你"顺手做更多"。

03｜tasks.md 模板：必须"可勾选、可验证"

下面是我推荐的 tasks 清单格式（把"完成定义"写死）：

md 复制代码

## Tasks
- [ ] 定位根因：列出证据（文件路径/函数/日志关键词）
- [ ] 最小修复：明确改动文件与改动点
- [ ] 单元测试：覆盖成功/失败/边界条件
- [ ] 验证步骤：本地验证 + CI 验证（如适用）
- [ ] 回滚策略：如何撤回改动
- [ ] 文档更新：README/变更说明（如适用）

注意：每一条任务都应该能回答"怎么验证"。

否则它就会变成愿望清单。

04｜把 Spec 工作流和 AI coding 接起来：三段式推进

你可以用"三段式"让智能体稳定交付，而不是随机游走：

先对齐规约（Spec）
- 让 AI 基于 proposal.md 复述目标与非目标
- 把硬规则置顶（不改 API/改动最小/必须验证）
再按任务清单执行（Tasks）
- 让 AI 逐项执行 tasks.md，每项必须给证据与验证方式
- 每完成一项就勾选并更新清单（避免"做了但没人知道"）
最后做验证与归档（Validate/Archive）
- 跑测试/静态检查/构建（按项目实际）
- 把本次变更的规约与结果沉淀下来

这套流程的价值是：

把智能体的输出从"灵感型回答"变成"按合同交付"。

05｜常见失败模式：为什么你写了 Spec 还是会跑偏？

Spec 太宽 ：目标/非目标不清晰
- 修复：补 Non-goals；补 Constraints；把"不要做什么"写出来
Tasks 不可验证 ：只有"优化/完善/改进"
- 修复：改成可验证动作（新增测试、输出证据、给验证步骤）
没有更新清单 ：做完了但任务不勾选
- 修复：强制"每完成一项就更新 tasks.md"，让进度可见

06｜系列导航（收藏用）

系列 01：从 Chat 到 Agent：4 个关键零件
系列 02：命令系统：从提示词模板到可扩展子命令
系列 03：@路径上下文：如何给材料而不喂爆上下文
系列 04：MCP 与工具闭环：注册、调用、回填与失败恢复
系列 05：上下文治理：清空/压缩/摘要与预算控制
系列 06：SubAgent：上下文隔离与模块化协作
系列 07（本文）：规约驱动：让交付可复现的 Spec 工作流
系列 08：迷你 CLI：从伪代码到最小可运行骨架

参考与致谢

阿里云开发者技术号原文：《AI coding 智能体设计》