AI 2026年5月28日 1 分钟阅读

Spec-Driven Development 实战指南：用规格说明书精准控制 AI 编码 Agent

tinyash 0 条评论

文章信息

发布时间 2026年5月28日
作者 tinyash
阅读时长 1 分钟阅读

AI 编码 Agent（Claude Code、Cursor 等）让开发效率大幅提升，但有个普遍痛点：你让它写一个功能，它理解的方向和你想要的不一样。需求沟通了一个回合，Agent 写出来的代码却只实现了需求的 60%。剩下的 40% 需要反复对话、多次修改，甚至重写。

Spec-Driven Development（SDD，规格驱动开发）正是解决这个问题的方案——先写规格说明书，再让 Agent 写代码。这在传统软件工程中已有类似实践（如 TDD、BDD），但结合 AI 编码 Agent 后，SDD 有了全新的生命力。

什么是 Spec-Driven Development？

SDD 的核心流程只有三步：

写 Spec：用自然语言描述功能需求、输入输出、边界条件
给 Agent：把 Spec 一次性喂给 AI 编码 Agent
验证交付：Agent 根据 Spec 生成代码，你检查是否符合预期

这个方法的好处在于：

减少误解：Agent 在执行前就理解完整需求，避免逐轮对话中的方向偏差
可复现：同一个 Spec 可以让不同 Agent 或同一 Agent 的不同 Session 产生一致的结果
可评审：Spec 本身可以被团队成员 review，在写代码前就统一理解

实战：用 Spec 写一个 Markdown 解析器

假设我们要让 Agent 写一个简单的 Markdown 转 HTML 的函数。传统的做法是对话式：

“帮我写个 markdown 解析器” Agent 开始写，但可能只处理了粗体和标题 “再加个代码块支持” Agent 修改，但可能和已有逻辑冲突

用 SDD 的做法就不一样了。先把下面这个 Spec 写好：

## 功能需求
实现一个 `md_to_html(markdown_text: str) -> str` 函数。

## 支持的语法
- 标题：# H1 到 ###### H6
- 粗体：**text** → text
- 斜体：*text* → text
- 行内代码：`code` → code
- 代码块：```...``` → ...
- 无序列表：- item → item
- 链接：[text](url) → text

## 边界条件
- 空字符串返回空字符串
- 嵌套格式（如粗体中的行内代码）需正确处理
- HTML 特殊字符需要转义（&, <, >）
- 未识别的 Markdown 语法保持原样输出

## 输出格式
单个 Python 文件，包含函数定义和类型注解。

把整个 Spec 一次性交给 AI 编码 Agent，你会得到远超对话式交互的结果。Agent 一次性处理了所有功能点和边界条件，生成的结构化代码几乎不需要修改。

现有的 SDD 工具生态

SDD 理念虽简单，但已经有了一些不错的工具来帮你落地：

1. Claude Skill for SDD

FredAntB 开源的 Spec-Driven-Development 是一个 Claude 自定义 Skill，让你在 Claude Code 中直接使用 /spec 命令启动 SDD 工作流。它包含 Spec 模板、示例和自动验证流程。

2. OpenSpec

Fission AI 的 OpenSpec 是一个更完整的规格说明框架，支持版本化 Spec、自动化测试生成和团队协作。它的核心理念是 “Spec as Code”——规格说明书本身也是代码的一部分，纳入版本管理。

3. Unspaghettit

刚发布的 Unspaghettit 将 Spec 变成可执行的——你定义的 Spec 不仅指导 Agent 写代码，还能直接验证输出是否符合预期。这意味着你可以在 CI 流程中加入 Spec 合规性检查。

4. Spec Kit

Comment #5 中提到的 Spec Kit 是另一个成熟的方案，它与其他工具如 Compound Engineering、Superpowers Skill 都提供了类似的 Spec 管理能力，各有侧重。

SDD 工作流的最佳实践

经过实践，这里总结几个提升 SDD 效果的经验：

1. Spec 要具体到边界条件

很多开发者写 Spec 只写功能需求，忽略了边界条件。Agent 对于边界情况的处理往往最不稳定。在 Spec 中明确列出空输入、异常、非法参数等场景，Agent 生成代码的质量会有质的提升。

2. 一个 Spec 对应一个功能

不要在一个 Spec 里塞多个不相关的功能。保持 Spec 的单一职责——一个 Spec 对应一个函数、一个组件或一个 API 端点。这样便于独立验证和修改。

3. 先审 Spec，再审代码

SDD 最大的价值在于在写代码前发现理解偏差。写完 Spec 后先给团队成员 review，确认功能描述正确后再交给 Agent 执行。这一步能从根本上减少返工。

4. Spec 纳入版本管理

把 .spec.md 文件和代码一起提交到 Git 仓库。当需求变更时，先改 Spec，再用 Agent 按新 Spec 重写代码。这不仅记录了需求的演进过程，也让后续维护者能理解每个功能的原始意图。

什么时候不该用 SDD？

SDD 并非银弹。以下几种情况，直接对话式交互反而更高效：

探索性开发：还没想清楚具体要什么，想快速试错
简单改动：改一个变量名、加一个日志，不值得写 Spec
Bug 修复：通常 Bug 描述本身就包含了 Spec 所需的所有信息

结语

Spec-Driven Development 不是新概念，但结合 AI 编码 Agent 后，它的价值被放大了。传统的对话式交互相当于”边想边做”，而 SDD 相当于”先画图纸再施工”。对于复杂功能、团队协作、需要维护的项目，SDD 能显著减少 Agent 的试错次数和你的返工时间。

下次要让 AI 编码 Agent 实现一个复杂功能时，别急着对话。花 5 分钟写个 Spec，效果会让你惊喜。

相关工具链接：