从 Vibe Coding 到可控交付：用 Spec-Driven Development 驾驭 AI 编程 Agent-育师

我是安徽最忧郁程序员无隅

让 AI 写出一段能运行的代码，已经不算难事。真正困难的是：项目变大、任务并行、上下文不断切换之后，AI 生成的代码还能不能遵守边界，能不能通过验证，能不能让下一个人继续维护。

一篇来自阿里技术的实践文章给出了一个很有代表性的答案：团队把第一天全部用于定义规格，后续再让 AI 并行实现。这个案例的启发并不是“AI 写代码有多快”，而是AI 的执行上限，往往取决于人类能否把意图表达成稳定、可验证的工程约束。

这套方法叫 Spec-Driven Development，简称 SDD。

一、SDD 的本质：代码不是起点，意图才是

SDD 通常被翻译为“规格驱动开发”。它要求团队先把要解决的问题、功能边界和验收标准写成结构化规格，再由开发者或编程 Agent 选择实现方式。

一句话概括就是：

人负责定义 WHAT，Agent 在约束内完成 HOW。

这里的 Spec 不是传统意义上写完就归档的需求文档，而是开发过程中的事实来源。代码、测试和 Review 都应该能够回到 Spec，回答两个问题：当前实现为什么存在？怎样才算完成？

这对编程 Agent 尤其重要。模糊需求会迫使 Agent 自己补齐缺失信息，而每一次“合理猜测”都可能偏离真实目标。Spec 通过成功指标、非目标和技术约束主动压缩猜测空间，让 Agent 知道哪些地方可以自主决策，哪些边界绝对不能突破。

GitHub 的 Spec Kit 官方文档把默认流程定义为Spec → Plan → Tasks → Implement，每个阶段产生的 Markdown 工件都会成为下一阶段的结构化上下文。这说明 SDD 并不是单纯“多写文档”，而是在为 Agent 建立稳定的上下文传递链路。GitHub Spec Kit 官方文档

二、主链路：Specify、Plan、Implement、Validate

一套可落地的 SDD 流程可以拆成四个阶段。

Specify：定义问题。输入是业务目标和现状，输出是可验证的需求规格。这个阶段要说清楚为什么做、谁会使用、做到什么程度算成功，以及本次明确不做什么。

Plan：设计方案。输入是已经确认的 Spec，输出是架构决策、模块边界、接口契约和风险处理方式。Plan 可以由 Agent 起草，但技术选型和关键取舍仍然需要人来审核。

Implement：执行任务。输入是经过审核的 Plan 和任务列表，输出是代码、测试与变更记录。Agent 的工作重点不是重新理解需求，而是逐项完成边界明确、可以独立验证的任务。

Validate：验证交付。输入是实现结果和 Spec 中的验收标准，输出是测试报告与 Review 结论。验证失败时，不应该只让 Agent 反复修改代码，还要判断问题究竟来自实现错误、Plan 缺陷，还是 Spec 本身遗漏了边界。

因此，SDD 不是一条只向前走的流水线，而是一个反馈闭环：

Specify → Plan → Implement → Validate ↑ │ └────── 反馈与修正 ────────┘

AWS 对 Kiro 的官方介绍也采用了类似思路：先把自然语言需求转化为详细的 Specs，再生成设计、数据流、代码和测试。这类产品的共同方向，是把一次性的 Prompt 变成可持续演进的工程工件。AWS Kiro 官方文档

三、四类文件：把长期原则逐层压缩成可执行任务

在实际项目中，可以用四类文件承接不同层次的信息。

constitution.md保存项目级长期原则，例如安全底线、日志规范、依赖策略和测试要求。它解决的是“每次任务都重复提醒 Agent”的问题。只要任务属于这个项目，就必须遵守这些原则。

spec.md定义当前功能的 WHAT。它应该包含问题陈述、成功指标、用户场景、验收标准、非目标和外部约束，但不要提前把某种实现方案写死。

plan.md负责 HOW。这里才讨论模块拆分、接口、数据结构、技术选型、兼容策略和风险。它是 Spec 与代码之间的技术桥梁。

tasks.md把 Plan 拆成可以独立完成、独立验证的原子任务。一个合格任务不仅描述“要做什么”，还要包含依赖关系和完成条件。

假设我们要给一个 Agent 应用增加“对话记忆”能力，一份最小 Spec 可以这样写：

Feature: 会话级记忆 Problem Statement: Agent 在多轮对话中无法稳定使用前文中的用户偏好。 Success Metrics: - 同一会话中可以读取最近 20 轮有效消息 - 新会话默认不继承旧会话内容 - 记忆读取失败时不阻塞主回答链路 Acceptance Criteria: - [ ] 相同 thread_id 可以恢复对应历史 - [ ] 不同 thread_id 之间的数据完全隔离 - [ ] 自动化测试覆盖正常读取、空记录和存储异常 Non-Goals: - 本期不实现跨会话长期记忆 - 本期不实现向量语义检索 Constraints: - 日志不得记录 Token、密码或完整私人对话

这个例子没有规定必须使用 Redis、PostgreSQL 或某个 Agent 框架，因为这些属于 Plan 的决策。判断 Spec 粒度是否合适，可以问一句：如果更换技术栈，这份需求仍然成立吗？如果答案是否定的，很可能已经把 HOW 误写进了 WHAT。

四、怎样在真实项目中开始：先做一个最小闭环

SDD 最容易走向两个极端：一端是只有一句自然语言需求，让 Agent 自由发挥；另一端是把 Spec 写成比代码还长的自然语言伪代码。更务实的做法，是先选择一个会影响模块行为的小功能，跑通最小闭环。

第一步，只写一份spec.md。重点补齐可测试的成功标准、Non-Goals 和约束，不急着引入复杂工具链。

第二步，让 Agent 根据 Spec 起草 Plan。人重点检查模块边界、异常路径、兼容性和安全风险。如果 Plan 暴露出需求盲点，先返回修改 Spec，不要带着错误前提继续编码。

第三步，把 Plan 拆成小任务。每个任务都要有明确输入、输出和验证方式，例如“迁移脚本能在空库执行成功”，而不是笼统地写“完成数据库开发”。

第四步，让测试和 Review 回到验收标准。Spec 不能替代代码审查，它只说明要做成什么样；实现是否安全、性能是否达标、代码是否可维护，仍然需要确定性的测试、静态检查和人工判断。

OpenSpec 的官方仓库强调“迭代而非瀑布”，并提供从探索、提案、应用到验证的增量工作流。这一点很关键：活的 Spec 会随着反馈更新，死的 Spec 才会退化成瀑布式文档。OpenSpec 官方仓库

Thoughtworks 技术雷达把 SDD 描述为仍在演进中的 AI 辅助开发方法，并提醒不同工具对任务规模的适应性差异明显，有些流程会生成难以审核的冗长规格。因此，现阶段更合理的态度不是把 SDD 当成万能答案，而是把它作为一种需要结合团队规模和任务风险逐步验证的工程实践。Thoughtworks Technology Radar

最终，SDD 的价值并不是让团队永远停留在写文档阶段，也不是让 Agent 取代技术判断。它真正解决的是：当代码生成越来越便宜时，如何让需求边界、设计理由和验收标准仍然可以被传递、检查和追踪。

模型负责提高生成速度，Spec 负责守住交付方向。