Spec Coding

Mar 04, 2026 · 4810 字

Spec Coding 的核心不是“让 AI 多写代码”，而是“让规格主导代码”。需求、边界、验收、非功能要求先被写成可执行的 spec，随后实现、测试、评审、发布都围绕同一份规格推进。很多团队在引入 AI 之后才真正感受到这一点：模型能力决定产出速度，规格质量决定产出上限。

起源与发展

Spec Coding 在术语上是新的，在思想上并不新。软件工程早就有一条稳定主线：把隐含需求外化为可验证约束，让实现行为绑定约束，而不是绑定个人理解。

这条主线在不同分支里一直存在。需求工程强调可验证需求，关注“需求是否能被证明已经满足”。契约式设计强调前置条件、后置条件、不变量，关注“行为是否违背约束”。测试驱动强调可执行反馈，关注“实现是否持续满足行为定义”。早在 2004 年 Agile Specification-Driven Development 一文就已提出测试与契约是互补规格，规格不应停留在前期文档，而应贯穿迭代。

AI 编程让这些老问题再次显形。Vibe Coding 能快速推进探索，但常见副作用也很稳定：需求漂移、边界遗漏、决策散落在聊天记录、多人协作时上下文失真。Spec Coding 的价值在这里变得具体：把“对话上下文”转换为“工程上下文”。

从问题空间和解空间看也更容易理解。问题空间回答“要解决什么”，包括业务目标、规则、风险、合规和不变量。解空间回答“怎么实现”，包括架构、模块、接口、数据和部署。项目失控往往不是实现能力不足，而是问题空间表达不完整，导致解空间被迫猜测。Spec 的作用就是把问题空间结构化，再把结构化约束映射到可执行任务和可验证结果。

规格驱动开发

规格驱动开发，即 Specification-Driven Development。它不是额外负担，而是一种交付组织方式：规格先行，设计和开发围绕规格展开，测试和发布对规格负责。

一份可用 spec 至少覆盖四类信息：

目标：要解决什么业务问题，成功标准是什么。
边界：In/Out 范围，异常路径，依赖和前提条件。
验收：可执行、可测量、可回归的验收条目。
约束：性能、安全、审计、兼容、成本、时效。

这四类信息并不是写作模板，它们对应软件工程产物。目标对应需求项，边界对应设计决策，验收对应测试计划，约束对应质量门禁。规格越完整，后续分歧越少，返工越可控。

Spec Coding、DDD（Domain-Driven Design，领域驱动设计）、TDD（Test-Driven Development，测试驱动开发）的关系可以分层看。DDD 负责业务语义建模，解决“系统该如何表达真实业务”。SDD 负责交付编排，解决“业务约束如何变成可执行任务”。TDD 负责实现校验，解决“代码行为如何持续正确”。三者协同后，模型、实现、验证形成闭环。

如果只有 DDD，没有 SDD，模型容易停在设计图上。如果只有 SDD，没有 TDD，规格难以持续验证。如果只有 TDD，没有 DDD，测试可以通过，但业务语义可能偏离。实践里最稳定的做法是：DDD 决定语义结构，SDD 决定执行结构，TDD 决定反馈结构。

Spec Coding 与 Vibe Coding 也可放在同一框架对比：

维度	Spec Coding	Vibe Coding
控制面	规格文本	对话上下文
起手方式	先定义目标与验收，再实现	先生成结果，再迭代修正
需求管理	显式边界，变更可追踪	隐式边界，变更易漂移
协作成本	前期高，后期低	前期低，后期高
质量稳定性	高，适合长期维护	波动大，依赖个人把控
典型场景	正式功能、多人协作、上线交付	原型探索、一次性脚本、灵感试验

这不是二选一关系。许多团队采用“先 Vibe，后 Spec”的节奏：用 Vibe Coding 迅速探索方向，再把共识固化为 spec，切换到 Spec Coding 完成工程交付。

具体实践

把 Spec Coding 放进软件工程流水线，通常会形成一条稳定链路：需求阶段写 spec 草案，设计阶段映射架构与接口，实现阶段按 spec 拆任务，测试阶段按验收条目生成自动化验证，发布阶段按 spec 设门禁，维护阶段坚持“先改 spec，再改代码和测试”。

这条链路的价值在于可追踪性。每次变更都能回答三个问题：改了什么，为什么改，影响了哪些行为。团队协作越复杂，这个能力越关键。

落地时不依赖某个 IDE，关键在仓库组织。一个常见结构如下：

.
├─ AGENTS.md
├─ specs/
│  ├─ README.md
│  ├─ order-refund.md
│  └─ order-refund.changelog.md
├─ tasks/
│  └─ order-refund.tasks.md
└─ tests/
   └─ refund.apply.spec.ts

AGENTS.md 管全局规则，specs/ 管需求与边界，tasks/ 管执行拆解，tests/ 管行为验证。这个分层能把讨论沉淀成资产，避免知识只留在聊天上下文。

AGENTS.md 的规则建议同时覆盖代码和流程：

## 代码

- 默认使用 TypeScript。
- 写入操作必须经由 service 层。
- 外部接口失败必须可重试或可补偿。

## 流程

- 任何功能变更先修改 spec，再修改代码。
- PR 说明必须引用 spec 和验收条目。
- 未覆盖验收测试的代码不得合并。

单个功能的 spec 可以保持简洁，但必须可执行：

# order-refund

## 目标

支持支付后 7 天内全额退款，退款状态全程可追踪。

## 范围

- In：退款申请、审核、状态通知。
- Out：财务对账、跨渠道清算。

## 规则

- 退款金额不得超过实付金额。
- 审核动作必须记录操作者和时间。
- 超时 10 秒返回可重试错误。

## 验收

- 7 天内订单可提交退款申请。
- 超过 7 天返回 `REFUND_WINDOW_EXPIRED`。
- 审核通过后订单状态变更为 `refunded` 并写入审计日志。

随后把 spec 映射到任务清单和测试清单：

# order-refund tasks

- [ ] API：新增 `POST /refund/apply`，对应验收 1、2。
- [ ] Domain：新增退款资格校验，覆盖 7 天窗口规则。
- [ ] Infra：新增审计日志写入，覆盖验收 3。
- [ ] Test：新增集成测试 `refund.apply.spec.ts`，覆盖验收 1、2、3。

这类“规格条目 -> 任务条目 -> 测试条目”的映射关系，就是 Spec Coding 的可执行形态。

实践里最常见的问题也集中在这里。第一类是把 spec 写成愿景文案，缺少边界和验收，文本好看但不可执行。第二类是把 spec 当冻结文档，不做变更管理，最终代码和 spec 分叉。第三类是 spec 不接入测试和发布门禁，规格没有约束力，只是参考意见。要避免这些问题，关键不是写更长的 spec，而是让 spec 进入执行、测试、评审、发布四个环节。

GitHub Spec Kit

GitHub Spec Kit 把这条链路做成可直接启用的工程模板和命令集，适合团队把“规格先行”固定成统一流程。

初始化可以用一次性命令，也可以持久安装后反复使用：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init --here --ai copilot
specify check

初始化完成后，仓库里会出现一组与代理工具相关的命令目录，以及 .specify/ 下的规格产物。对工程协作影响最大的点有两个：

规格、计划、任务会按固定路径沉淀，讨论内容不再散落在聊天记录里。
同一项目可切换不同 agent，但保持同一套 spec 文件和推进节奏。

结合日常开发，比较稳的做法是把 Spec Kit 嵌进现有 PR 流程。

新功能流程

下面这组命令可以直接作为一个完整起手流程：

git switch -c feat/refund-window
/speckit.specify "支持退款窗口从 7 天调整为 15 天，并增加风控二次校验"
/speckit.plan "技术栈保持不变，优先复用现有退款服务与审计链路"
/speckit.tasks
specify check

这一步里每个产物要写的重点可以压缩成四行：

spec.md：写清目标、范围、验收、非功能约束，尤其是边界条件和失败路径。
plan.md：写实现方案与取舍，明确改哪些模块、接口是否变化、数据是否迁移、风险怎么控。
tasks.md：拆成可执行任务并标注依赖关系，每条任务最好能对应一个可验证结果。
PR 描述：引用 spec 条目和任务编号，评审结论按验收条目逐条对照。

增量更新流程

功能做了一半出现需求变更时，不建议直接改代码，先回到规格链路：

/speckit.specify "在已有退款功能上新增 VIP 用户 30 天窗口，普通用户维持 15 天"
/speckit.plan "补充分层鉴权策略与灰度发布计划，其他模块不动"
/speckit.tasks
specify check

这个更新流程对应的是“先改规范，再改实现”：

更新 spec.md：新增变更背景，补充被影响的规则和验收条目。
更新 plan.md：只改受影响模块，标注不改动范围，避免计划膨胀。
更新 tasks.md：删除失效任务，新增变更任务，给任务补上验收映射。
更新测试：按新验收补测试或调断言，保证 CI 对齐最新 spec。

Spec Kit 也适合增量接入旧项目。不要一上来全量改造，优先挑一个高频变更模块做试点，把 spec -> plan -> tasks -> test 链路跑通，再逐步推广到其他模块。这样能避免模板引入成本过高，也能快速验证团队是否真正按规格协作。