用 AI 写代码，最容易获得的是一份看起来已经完成的实现。真正困难的是确认：它做的是不是我们想要的东西？
一句“帮我加一个导出功能”，AI 可以很快写出按钮、接口和下载逻辑。但导出当前页还是全部筛选结果？哪些字段允许导出？没有数据时怎么办？这些问题如果没有提前说清楚，就会变成实现里的隐含假设。
Spec 驱动开发想解决的，正是需求从人的想法走到代码之间的偏差。
什么是 Spec 驱动开发
Spec 是 Specification 的简称，指对软件预期行为、约束与验收条件的明确描述。本文使用 Spec-Driven Development（SDD，规范驱动开发） 这一名称，也沿用“Spec Coding”作为便于交流的说法。
在 AI 辅助开发中，它的基本做法是：先把需求整理成可检查的规范，再让 Coding Agent 按规范规划和实现，最后逐项验证结果。
这里的“规范”可以很短。一项小功能，只要说清楚目标、边界、关键行为和验收条件，就已经有了落脚点。
规范描述预期，代码承担实现，测试和评审提供证据。 三者需要持续对齐。文档写得再完整，也不能自动保证 AI 遵守，更不能代替运行结果。
与直接对话式开发有什么区别
在偏 Vibe Coding 的工作方式中，我们往往通过连续提示、观察效果和补充修改来推进。它适合快速探索，但需求容易分散在聊天记录里。
采用 SDD 后，已经确认的决定会进入项目文件，后续实现和修改都有明确参照。
| 关注点 | 主要依靠对话推进 | 采用规范驱动 |
|---|---|---|
| 需求记录 | 散落在多轮消息中 | 收敛到可版本管理的文件 |
| 模糊问题 | 可能在实现时由 AI 补全 | 显式标出假设和待确认项 |
| 修改依据 | 继续补一句提示词 | 更新相关规范及验收条件 |
| 完成判断 | 页面看起来可用、AI 声称完成 | 对照约定检查行为和证据 |
| 接手成本 | 重新解释聊天背景 | 阅读当前规范和关键决策 |
这两种方式可以衔接：先用原型探索交互，方向明确后，再把已经确认的行为固化成规范。
三个值得借鉴的开源项目
以下项目定位根据 2026 年 9 月 17 日的官方仓库说明核对。工具会持续演进，具体命令和目录以所使用版本为准；使用感受与选择建议属于个人判断。
Spec Kit：结构完整的规范驱动工具链
GitHub Spec Kit 提供结构化流程和模板，将规范、技术计划、任务拆分、实现及一致性检查串联起来，也支持在已有项目中使用。
我目前体验下来，觉得它的流程比较完整，同时也偏重量级。我更喜欢把需求拆得细一些，每次围绕一个能独立验收的变化推进。
如果团队需要统一项目原则、规划和交付方式，可以参考它的完整流程；具体采用多少环节，仍然需要结合项目规模裁剪。
OpenSpec：围绕一次变更组织项目资产
OpenSpec 强调轻量、迭代和已有项目中的增量变更。官方示例将一次变更组织为以下几类产物：
| 产物 | 用途 |
|---|---|
proposal.md |
解释变更动机和范围 |
specs/ |
描述需求及具体场景 |
design.md |
记录技术方案 |
tasks.md |
跟踪实施任务 |
严格来说，这里是三个 Markdown 文件和一个规范目录。变更完成后，可以归档变更记录并更新规范。
我比较认可这种组织方式：把讨论中确认的需求、方案和任务沉淀下来，成为后续开发可复用的项目资产。这里应当保留的是经过整理的结论；完整聊天记录可以另作追溯，但不宜全部塞进当前规范。
Superpowers：把工程习惯编排成 Agent Skills
Superpowers 的定位更广，是一套基于可组合 Skills 的开发方法。它覆盖需求澄清、设计确认、任务计划、测试驱动开发和代码评审等环节。
我最关注的是它对澄清和设计确认的强调：先让人能够读懂并确认方案，再继续实现，减少 AI 根据模糊描述自行补全需求的机会。
借鉴这类流程时，我会把确认点放在业务规则、范围和架构取舍上；普通实现细节则交给 Agent 在既定约束内处理，避免每一步都打断开发。
我会怎样选择
下面是我的选型思路，并非三者能力的硬性边界。
| 当前主要问题 | 优先借鉴 |
|---|---|
| 缺少统一的项目原则和开发流程 | Spec Kit 的结构化流程 |
| 已有项目持续加功能，希望每次变更可追溯 | OpenSpec 的变更组织方式 |
| AI 经常跳过澄清、验证和评审 | Superpowers 的工程行为约束 |
可以借鉴多个项目，但同一个环节最好只保留一套主要流程，避免两套工具反复生成内容相似、状态不一致的计划。
一个小例子：怎样把“导出功能”写清楚
假设要给经营报表增加 CSV 导出。下面是一份自定义的轻量 Spec 示例，并非上述工具的官方模板。
# 变更：导出经营报表 CSV
## 目标
用户可以导出当前筛选条件下的经营数据，用于线下核对。
## 范围
- 导出所有符合当前筛选条件且用户有权查看的记录。
- 导出字段及顺序与本次确认的报表字段清单一致。
- 本次只支持 CSV。
## 非目标
- 不增加定时导出、邮件发送或自定义列功能。
- 不修改原有经营指标计算口径。
## 行为与验收
- AC-01：筛选某品牌和月份后，导出结果只包含对应数据。
- AC-02：符合条件的数据超过一页时，导出包含全部匹配记录。
- AC-03：没有匹配记录时，提示“当前筛选条件下暂无数据”。
- AC-04：无权查看的数据，即使直接请求导出接口也不能获取。
- AC-05：导出失败时显示失败提示，按钮恢复可操作状态。
## 开发前待确认
- 最大允许导出的记录数，以及超过限制后的处理方式。
- CSV 编码、金额精度和文件命名规则。
这份规范的价值在于提前暴露了会影响实现的问题。“超过一页是否全部导出”会影响查询方式，“最大记录数”可能决定是否需要异步任务。
这些问题没有确认时，应明确保留为待确认项。Agent 可以提出选项和建议，但不能把建议悄悄当成已批准需求。
确认后，再决定技术方案、拆分任务，并按验收编号验证。这样，“开发完成”才有具体含义。
我更倾向于怎样落地
一次只推进一个可验收的变化
“完成整个后台管理系统”很难评审。“增加报表筛选”“增加 CSV 导出”“补上导出权限校验”，则更容易定位范围和风险。
拆分时仍要保持业务完整性。例如，涉及敏感数据的导出功能，权限校验应当和功能一起交付，不能为了缩小任务而推迟安全边界。
把长期规则和本次需求分开
项目级规则负责技术栈、目录约定、测试要求和通用约束；本次 Spec 只描述这次改什么；关键架构决策则单独记录原因和取舍。
这样可以避免每次新增一个按钮，都重新复制几十页项目背景，也能减少多份文档同时定义同一规则造成的冲突。
让任务、验收和证据对应起来
任务清单描述要做的工作，验收条件描述用户应当看到的行为，两者不能混为一谈。
“新增导出接口”是一项任务；“用户只能导出自己有权访问的数据”是一项验收条件。接口存在，并不能证明权限行为正确。
我希望 Agent 的交付说明能直接回答：对应哪些验收条件、改了什么、怎样验证、还有哪些未验证。重要规则应尽量通过自动化测试或其他可重复检查来约束。
变化发生时，同步更新规范
实际开发中，发现方案不合理、接口受限或需求变化都很正常。此时应先说明影响，修订相关规范和任务，再继续实现。
如果代码已经偏离规范，就需要判断：是实现错误，还是预期已经改变。前者修代码，后者更新规范并记录理由，避免两套说法长期并存。
SDD 也会带来新的问题
文档越写越长，人却越来越看不懂
AI 很容易把一个小需求扩展成完整产品规划，生成大量背景、设想和实现细节。审阅成本一旦超过人的耐心，确认就会变成走过场。
我的处理原则是：主文档优先呈现目标、范围、关键规则和验收条件；补充材料按需引用。先看短摘要，再审阅真正影响决策的部分。过长时优先检查需求是否该拆分，而不是仅仅压缩措辞。
AI 把建议写成需求，越做越多
“顺手加一个缓存”“补一套管理后台”“以后可能需要多租户”，都可能让任务悄悄变大。
可以将内容明确分成已确认需求、待确认问题和未来建议。当前实现只覆盖已确认范围；新增依赖、公共接口变化和数据结构调整，需要说明必要性及影响。
AI 写了规范，却没有按规范实现
规范始终是一种约束输入，模型仍可能遗漏、误解或偏离。不能只让同一个 Agent 根据自己的任务清单宣布完成。
验收应回到原始行为：测试是否覆盖关键场景？失败路径是否检查？页面和接口是否符合约定？测试通过也只说明已覆盖的部分，不等于全部需求都被证明正确。
文档生成得很快，维护却被忽略
失效的文档可能持续误导下一轮开发。比保存大量文件更重要的是明确：哪份规范代表当前预期，哪些是历史记录，哪些仍然只是提案。
归档时要清理过期状态，并保持当前规范可读。历史决策用于解释来路，当前规范用于指导下一次变更。
哪些场景值得使用 SDD
我会根据误解需求的代价和协作成本，决定规范写到什么程度。
| 场景 | 建议投入 |
|---|---|
| 多人协作、跨前后端或跨服务修改 | 写清接口、职责、兼容性和验收条件 |
| 权限、经营指标、异步任务等规则较多的功能 | 补齐边界、异常路径及关键不变量 |
| 已有系统持续迭代 | 围绕单次变更记录影响和决策 |
| 需要长期维护或经常更换 Agent 会话 | 维护简洁、可信的当前规范 |
| 一次性原型、尚在探索的交互 | 先验证方向，再固化已确认部分 |
| 错别字、样式微调等低风险修改 | 使用简短任务描述和必要检查即可 |
需求频繁变化时，SDD 的价值在于让变化可见、影响可追溯。它要求持续维护规范，也因此有成本，不能指望先写一份大文档就一次解决后续所有问题。
写在最后
对我来说，Spec 驱动开发最值得保留的习惯，是在动手前明确目标和边界，在交付时拿出对应的验证结果。
工具可以帮助组织文件、触发流程和追踪任务，但业务判断仍然需要人参与。我更愿意从一份能读懂、能执行、能验收的小规范开始，让每次确认都实际影响开发，让每次实现都能回到约定上接受检查。