SDD 规范驱动开发（Spec-Driven Development）培训文档

面向研发团队的 SDD / Spec Coding 入门与落地培训材料适用对象：使用 Cursor / Claude Code / Copilot 等 AI 编码工具的工程师、技术负责人版本：v1.0 ｜整理时间：2026-06

什么是 SDD（规范驱动开发）
SDD 与 Vibe Coding（氛围编程）的区别
什么是"轻量 Spec"
SDD 能借助的工具
业界落地情况
规范文件（CLAUDE.md / Skill / Rules 等）对开发的帮助
最新业界动态：Loop（内外环）概念与 Agentic 工程
团队落地建议（结合本仓库）
参考链接

1. 什么是 SDD（规范驱动开发）

1.1 一句话定义

规范驱动开发（Spec-Driven Development，简称 SDD）：把"规范说明（Spec）"作为整个开发过程的唯一真相源（Single Source of Truth），让需求、约束、验收标准先以结构化、可版本化、可验证的文档形式固化下来，再由 AI Agent（或人）据此生成代码、测试和文档。

用一句在业界广为流传的话概括：

"Talk is cheap, show me the code." —— Linus Torvalds "Code is cheap, show me the markdown." —— AI 时代的新版本

也就是说：在 AI 能秒级产出代码的今天，代码逐渐变成"意图"的副产品，真正稀缺且会"复利增值"的，是那份清晰编码了意图、约束、取舍和成功标准的 Markdown 规范。

1.2 它"翻转"了什么？

几十年来软件开发的逻辑是：代码是王，文档是脚手架——规范只是开工前临时搭的架子，等"真正的编码工作"开始就被丢弃。

SDD 把这个关系反转（flips the script）：

传统模式	SDD 模式
规范 → 指导编码 → 被丢弃	规范 → 直接生成实现
PRD 是实现的"参考"	PRD 是产生实现的"源头"
代码是主产物	规范是主产物，代码是派生物
文档容易过时、与代码脱节	规范是"活的"、随项目演进的可执行制品

一个精炼的比喻："Spec 是对你思考过程的版本控制（Version control for your thinking）"。

1.3 谁提出 / 推动的？

SDD 不是某一个人独创的"专利"，而是 AI 编码浪潮下多方共同推动形成的范式。关键节点：

2025-02：Andrej Karpathy 提出 "Vibe Coding（氛围编程）" 一词，描述"凭感觉对着 AI 提示词反复迭代"的编码方式。
2025-07：Amazon 发布 Kiro——首个明确以"规范驱动"为核心理念的 Agentic IDE，把 requirements.md / design.md / tasks.md 作为一等公民。
2025-08：GitHub 开源 Spec Kit（github/spec-kit），提供 CLI + 模板，把 SDD 工作流标准化、工具化（截至 2026 年已超过 11 万 Star）。
2026-初：Karpathy 本人公开表示 Vibe Coding 时代正在结束，"我们正进入 **Agentic Engineering（智能体工程）**的时代——围绕详细规范编排 Agent，并保留人类监督"。
微软（Microsoft for Developers）、Thoughtworks、Martin Fowler 团队等持续输出方法论与工具评测，SDD 成为 2026 年 AI-Native 工程的主流方法论之一。

1.4 为什么要 SDD？能解决什么问题？

一句话：“纯靠AI写出来的屎山代码，谁来维护？铺开用时，多团队协作，会是一颗定时炸弹，不知道在哪个功能上就炸了！”

AI 让"写代码"变快了，但速度本身不等于好结果。直接对着 AI"提示—生成—修补"会带来一系列问题，SDD 正是针对这些痛点：

痛点（无 SDD）	SDD 如何解决
需求漂移（Requirements Drift）：代码越改越偏离最初意图	规范是唯一真相源，所有产出都对齐规范，从设计上消除漂移
上下文丢失：换一个会话、换一个 Agent，之前的决策全没了	规范随仓库版本化保存，跨会话、跨 Agent、跨人都能延续上下文
"三个月之墙"：氛围编程的原型在约 3 个月后技术债集中爆发	提前固化约束与边界，把"硬思考"前置，避免债务累积
多人协作冲突：聊天记录无法共享、无法 Review	规范可评审、可 Diff、可测试，团队（含 AI）共享同一份真相
AI 一次做太多导致出错	规范被拆成有边界的小任务（Tasks），Agent 分步执行、逐步验证
架构 / 契约违规，单测查不出	规范作为"可执行的构建闸门"，强制约束架构一致性与 API 契约

一句话：SDD = 用结构化规范"先对齐、再加速"，把 AI 从"猜你想要什么"变成"按你写明的去执行"。

2. SDD 与 Vibe Coding（氛围编程）的区别

二者并不是"谁取代谁"，而是 AI 辅助编程光谱的两端，分别擅长不同场景。

2.1 核心循环对比

	Vibe Coding（氛围编程）	Spec-Driven Development（规范驱动）
循环模式	`Prompt → Code → Patch`（提示→生成→修补）	`Specify → Plan → Tasks → Implement → Verify`（规范→计划→任务→实现→验证）
首要目标	速度、探索、创意	可维护性、正确性、可持续
意图载体	一次性的对话提示词（聊完即弃）	版本化、可评审的规范文件（活在代码库里）
典型问题	"这东西大概长啥样？"	"这东西必须严格这样工作。"
擅长	原型、Demo、UI/展示层、探索阶段	业务逻辑、校验、合规、核心系统、长期演进
风险	技术债、架构漂移、难以规模化	前期有一定额外开销（写规范）
协作	难以多人协作（聊天记录私有）	天然适合团队（规范随 PR 流转）

2.2 关键差异：规范"活在代码库里"

Vibe Coding 与 SDD 最本质的区别在于——

Vibe Coding 的意图是你打一次就忘的提示词；
SDD 的规范是版本化、可评审、团队（含 AI）共享的真相源：
- 它就放在代码旁边（live next to the code）；
- 它随系统一起演进（evolve with the system）；
- 它可以被评审和测试（reviewed and tested）；
- 当需求变化时，先改规范，生成的代码只是实现细节。

2.3 不是二选一：混合（Hybrid）才是主流

业界共识是 "结构化探索 + 活规范（Structured exploration with living specs）"：

用 Vibe Coding 探索：快速试错，发现真正的需求、验证可行性；
把成功的模式固化为规范：在进入生产部署前，把探索出来的方案写成版本化的规范；
用 SDD 保障质量：核心 / 长期模块走规范驱动，确保正确性与可维护性。

经验法则：

UI / 展示层、探索性工作 → 偏 Vibe Coding
业务逻辑、校验、合规、正确性要求高 → 必须 SDD
从 0 到 1 的核心系统、长期演进的企业应用 → SDD 为默认
短期一次性脚本 / 内部小工具 → 轻量 Spec 或纯 Vibe

3. 什么是"轻量 Spec"

并不是所有项目都需要厚重的规范文档。业界把 SDD 大致分成三个流派（粒度由轻到重）：

流派	规范形态	是否强制规范-代码同步	适用场景
轻量派 / Spec-First（规范先行）	Markdown 清单、任务描述等简单形式	否，归档为决策记录即可	快速原型、探索性开发、小团队内部工具、脚本
传统派 / Spec-Anchored（规范锚定）	完整规范文档，随系统长期维护	是，规范随项目演进	长期演进的企业应用
激进派 / Spec-as-Source（规范即源码）	规范是主制品，代码由规范生成（如 Tessl，代码顶部标注 `// GENERATED FROM SPEC - DO NOT EDIT`）	完全同步，1:1 映射	从 0 到 1 的核心系统（仍在探索阶段）

3.1 轻量 Spec 的定义与特征

轻量 Spec = 用最低成本把"要做什么 / 为什么 / 边界 / 验收标准"讲清楚的结构化文档。

它的核心价值：

极低成本：只用 Markdown + 简单 YAML，无需学习复杂 DSL，10 分钟即可对齐目标；
思维澄清：强制开发前明确"要做什么"，避免直接陷入氛围编程；
快速共识：团队（含 AI）在很短时间内对齐目标、边界和验收条件；
灵活调整：实现阶段允许合理偏离，不过度约束；
决策记录：完成后作为历史决策归档，不强制长期同步维护。

3.2 一个"好规范"应包含的要素

无论轻重，一份能让 AI 稳定执行的规范通常应覆盖这 6 个要素：

Outcomes（预期结果 / 目标）：要达成什么；
Scope boundaries（范围边界）：做什么、不做什么；
Constraints（约束）：技术栈、性能、安全、合规等不可违背项；
Prior decisions（既有决策）：已经定下的设计前提；
Task breakdown（任务拆分）：拆成可并行、可独立验证的小任务；
Verification criteria（验收标准）：怎样算"完成"（Definition of Done）。

3.3 轻量 Spec 的 4 条好规范特性

维度	说明
明确性	对系统行为、约束、边界有清晰描述，避免歧义
结构化	能被工具或 AI 稳定解析（Markdown / YAML / Schema），不要写成大段散文
可验证	能映射到测试或校验规则，确保规范与实现一致
可演进	支持版本化、Diff、回滚，纳入 Git 管理

3.4 常见误区（务必避免）

❌ 误区	后果	✅ 正确做法
把 README 当规范	规范无法验证	使用结构化清单 / Schema
规范写成大段散文	AI 无法稳定解析	采用结构化格式（清单、表格、YAML）
规范和实现不做 Diff 校验	规范与代码脱节	引入漂移检测 / Reconcile
没有版本化策略	无法回溯	规范纳入 Git 管理
过度细化规范	效率低下	平衡粒度，按场景选轻重

4. SDD 能借助的工具

4.1 主流 SDD 工具对比

工具	出品方	规范类型	编排范围	最适合
GitHub Spec Kit	GitHub	静态 Markdown	无（Agent 无关，可配各种助手）	跨 Agent 标准化、可定制化最强
Amazon Kiro	AWS	静态（EARS 语法）	单 Agent + Hooks	AWS 原生、需人工评审规范的项目
Tessl	Tessl	活规范（规范即源码）	1:1 规范↔代码映射	探索 Spec-as-Source（Beta 阶段）
OpenSpec	开源	半活（delta 标记）	无（Agent 无关）	棕地（已有代码）迭代式改造
BMAD-METHOD	开源	静态（docs-as-code）	21+ 角色化 Agent	框架重、企业级规划
Cursor + .cursor/rules	Cursor	类规范（Rules）	单 Agent	已在用 Cursor 的开发者，零迁移成本

4.2 GitHub Spec Kit 工作流（最具代表性）

Spec Kit 通过在 AI 助手里输入斜杠命令来驱动，每个命令对应一个阶段，所有产物直接落到工作区：


/constitution → /specify → /plan → /tasks → /implement

命令	作用
`/speckit.constitution`	创建 / 更新项目宪法：不可变的治理原则与开发准则（技术栈偏好、代码质量标准、禁止过度设计等）。这是一份"威力很大的规则文件"，被整个工作流大量引用。
`/speckit.specify`	定义要做什么（What）和为什么（Why）——需求、用户故事。显式排除技术选型。
`/speckit.plan`	定义怎么做（How）——框架、库、数据库、基础设施、数据契约、quickstart 等技术方案。
`/speckit.tasks`	把计划拆成可执行、分阶段的任务列表。
`/speckit.taskstoissues`	把任务列表转成 GitHub Issues 便于跟踪。
`/speckit.implement`	让 Agent 按计划执行所有任务，生成代码。

安装（Specify CLI，基于 uv）：

bash
uvx specify bootstrap

4.3 Amazon Kiro 的三件套 + EARS

Kiro 在编码前先生成三个互相联动的 Markdown 制品：

requirements.md：用 EARS 语法（Easy Approach to Requirements Syntax，源自 Rolls-Royce 喷气发动机适航分析）写用户故事与验收标准，消除歧义。典型句式：
```
WHEN [条件] THE SYSTEM SHALL [行为]
```
design.md：技术架构、时序图、数据模型、API 契约、实现考量。
tasks.md：映射到需求的实现任务清单。

特点：三个文件是联动的——改 requirements.md 会通过 "Refine" 更新 design.md，再通过 "Update tasks" 映射到 tasks.md，规范变更会结构化传播。配合 Steering（持久化项目前提，放 .kiro/steering/）和 Hooks（自动化测试生成等）。

4.4 通用编码助手的"规范化"能力

即使不用专门的 SDD 工具，主流 AI 编码助手都已内置"规范 / 规则"机制：

Cursor：.cursor/rules/*.mdc（带 YAML frontmatter，可按文件/目录 glob 范围生效）、Plan Mode、AGENTS.md；
Claude Code：CLAUDE.md + .claude/rules/，支持分层、可导入的项目配置；
GitHub Copilot：AGENTS.md + 自定义 Agent 定义；
Windsurf：Rules + Workflows；
AGENTS.md：跨多家 Agent（Codex、Copilot 等）通用的轻量标准，提供分层、即时的上下文。

注：本仓库已经在用其中多种——根目录的 CLAUDE.md、.cursor/rules/rules.mdc、.cursor/skills/ 都是 SDD 思想的具体体现（详见第 6 节）。

5. 业界落地情况

5.1 整体态势

GitHub Spec Kit 一年内 Star 数突破 11 万、220+ 贡献者、160+ 个版本发布，是 SDD 工具化的事实标杆。
有文章统计，围绕 SDD 的 Agentic 编码框架已超过 30+（Spec Kit、OpenSpec、GSD、Devika、Tessl……），并提出"SDD 正在吞噬软件工程（Spec-Driven Development Is Eating Software Engineering）"的判断。
Karpathy 公开表示氛围编程时代结束，转向 Agentic Engineering。
微软（Azure + GitHub）演示了端到端 AI-Led SDLC，把 SDD 作为核心拼图，并预言相当一部分内环编码工作将在 12 个月内被重塑。
McKinsey 调研指出：成功的 SDD 落地都使用了确定性编排（deterministic orchestration）做流程控制、有界 Agent 执行（bounded agent execution）、以及每步的自动化评估（automated evaluation）。

5.2 把"规范作为运营基础设施"的趋势

业界对工具的核心区分点正在变成：规范到底是"读一次的文档"，还是"Agent 持续执行的活资产"。

静态文档型：Spec Kit（Markdown）、Kiro（EARS）；
半活型：OpenSpec（delta 标记）；
活规范型 / 自动更新：Augment Cosmos、Tessl（规范即源码）。

趋势是朝"活规范 + 漂移检测 + CI 中校验不变量（invariants）"演进：工程师定义不变量 → 作为 CI/CD 一部分 → Agent 持续保证代码与规范一致。

5.3 多 Agent 协作模式（Coordinator / Implementor / Verifier）

SDD 在规模化时最被低估的实践是：让一个独立的 Agent 去"检查"工作，而不是信任执行 Agent 自检。


Coordinator（拆解规范、分派任务）
   ├── Implementor A（按子规范实现）
   ├── Implementor B（并行实现）
   └── Verifier（对照规范验收，发现冲突再合并）

Implementor 与 Verifier 目标相反——一个为"完成任务"优化，一个为"找出失败"优化。这迫使规范必须包含显式的验收标准，从而反过来改进了规范本身，也让并行 Agent 工作流更安全。

6. 规范文件（CLAUDE.md / Skill / Rules 等）对开发的帮助

这一节把视角拉回本仓库：在项目里增加规范文件，本质上就是在落地 SDD 中"宪法 / 规则 / 记忆"的部分。

6.1 这些规范文件分别是什么

文件 / 机制	类比 SDD 中的角色	作用
`CLAUDE.md`（本仓库根目录已有）	项目宪法（Constitution）	约束代码风格与实现方式：优先复用框架能力、分层约定、API 设计规范、事务/权限/日志规范、提交前自检清单等
*`.cursor/rules/.mdc`**（本仓库已有）	规则文件（Rules）	按文件/目录范围生效的精确指令，约束 AI 在特定上下文的行为
`.cursor/skills/`（本仓库已有，如 `cal-sql-migration`）	可复用技能（Skill）	把某类专门任务（如生成增量 SQL 迁移）的领域知识与步骤固化，AI 命中即按既定流程执行
`AGENTS.md`	跨 Agent 通用上下文	多种 AI 工具都能读取的轻量标准
`.specify/memory/`、`.kiro/steering/`	记忆库（Memory Bank）	跨会话保存项目前提与决策

6.2 对开发的实际帮助

一致性：所有 AI 产出都遵循同一套约定（例如本仓库 CLAUDE.md 要求"优先 XpModelViewSet、过滤写进 FilterSet、批量写操作必须事务、软删除走 deleted 字段"），避免每个人/每次会话风格漂移。
降低沟通成本：新成员（和 AI）读规范文件即可快速对齐，无需口口相传。
质量闸门：规则把"提交前自检"（是否复用框架、是否保证权限/事务/日志、是否向后兼容、是否补测试）变成默认动作。
可复用的专业能力：Skill 把"高频且有套路"的任务（如 SQL 迁移、测试用例生成）变成可一键调用的标准流程，减少重复造轮子。
上下文持久化：规范文件随 Git 版本化，跨会话、跨人、跨 Agent 都能延续，正是 SDD"活规范"的精神。

6.3 本仓库现状（已具备 SDD 雏形）

本仓库其实已经在实践 SDD 的关键要素：

宪法：CLAUDE.md（Django + DRF 代码风格与分层约定）；
规则：.cursor/rules/rules.mdc；
技能：.cursor/skills/cal-sql-migration/（增量 SQL 迁移）、testcase-generator（测试用例生成）；
需求/规划文档：docs/ 下大量 .md 与需求表（如《标定管理平台开发需求.md》《远程标定2026下半年规划.md》）。

改进方向：可以把 docs/ 里的需求文档进一步结构化（明确目标 / 边界 / 约束 / 验收标准），让它们从"参考文档"升级为"可驱动 AI 实现的轻量 Spec"。

7. 最新业界动态：Loop（内外环）概念与 Agentic 工程

7.1 从"写代码"到"Harness Engineering（编排工程）"

最新的核心概念是把开发过程拆成多个循环（Loop），人类与 Agent 各司其职。常见的是"内环 / 外环"双环，也有更细的"三环"划分。

双环模型（Inner / Outer Loop）


        ┌─────────────────── 外环 Outer Loop（人主导）───────────────────┐
        │  设定战略目标 · 根据真实反馈精炼规范 · 维护 Harness（编排/指标/质量闸门） │
        │                                                                  │
        │     ┌────────── 内环 Inner Loop（Agent 自主）──────────┐          │
        │     │  生成代码 + 测试 → 运行验证 → 自我纠错 → 直到匹配规范  │          │
        │     └───────────────────────────────────────────────┘          │
        │                       ▲ 软件交付给真实用户，收集反馈 ─┘            │
        └──────────────────────────────────────────────────────────────┘

内环（Inner Loop）= 目标驱动的执行：Agent 全自主地"生成代码与测试 → 运行验证 → 自我纠错"，直到产出匹配当前规范。这是 Copilot / Cursor / Claude Code 等工具所在的层。
外环（Outer Loop）= 软件与真实世界相遇：人类设定方向、把软件交给用户/团队/客户、收集反馈、更新规范，再触发内环实现变更。
一切都是持续迭代的闭环：让软件和规范在真实使用中不断变好，正确性被持续强制保证。

三环模型（更细的视角）

循环	时间尺度	谁在做	关注点
内环 Inner	秒~分钟	AI 编码工具	请求-产出-验证的快速协作
中环 Middle	小时~天	上下文工程（Context Engineering）	会话间上下文管理、多 Agent 并行协调
外环 Outer	周~月	PM / 架构师	架构、API 稳定性、工作区划分、范围与取舍

落地建议（业界共识）：先从外环入手——先把架构、规范、团队协作理顺；内环工具（Copilot / Cursor / Claude Code）很容易上手，真正决定成败的是围绕它们的组织与流程变化。

7.2 Reconcile / Archive：双环奇偶校验（Double-Loop Parity）

Spec Kit 社区为解决"代码与规范漂移"提出了两个扩展，正好对应内外环：

spec-kit-reconcile（内环）：当实现过程中代码偏离了规范，运行
```
/speckit.reconcile.run "我加了一个新路由，并改了按钮名称"
```
它会精准更新当前 feature 规范，并在 tasks.md 追加补救任务，让一切重新同步。
spec-kit-archive（外环）：feature 合并后运行
```
/speckit.archive.run
```
它把该 feature 规范的"增量（delta）"合并进中央的活项目记忆 .specify/memory/spec.md。

这种"双环奇偶校验"保证：开发期间当前 feature 是正确的；合并之后项目"记住"了正确的状态。

7.3 几个值得记住的最新判断

"Code is cheap, show me the markdown"：代码是产物，规范才是会复利增值的资产。
范式转移：从"AI 辅助任务" → "AI-Native / Agentic 工作流"；限制因素不再是"代码生成多快"，而是"意图能多清晰地被捕获、共享、验证"。
Spec-as-Source（规范即源码）：部分平台（Tessl 等）正在探索"规范是源码、代码是编译产物"，代码顶部甚至标注 // GENERATED FROM SPEC - DO NOT EDIT。这仍处早期，但代表了一种可能的未来方向。

8. 团队落地建议（结合本仓库）

本节为落地清单，便于团队按部就班实践。

沿用并强化宪法：维护好根目录 CLAUDE.md，作为 Django + DRF 项目的"不可变原则"。
需求文档结构化：把 docs/ 下的需求/规划文档，按"目标 / 范围边界 / 约束 / 任务拆分 / 验收标准"6 要素重写成轻量 Spec。
分场景选粒度：
- 核心业务（标定流程、权限、数据一致性）→ 完整规范 + 测试契约；
- 内部脚本 / 一次性工具 → 轻量 Spec 或 Vibe Coding；
善用 Skill：复用 cal-sql-migration、testcase-generator 等已有技能，把高频套路任务标准化。
建立内外环习惯：
- 内环：让 AI"生成→自测→自纠"，并用 ReadLints / 测试做验证闸门；
- 外环：feature 完成后回写规范 / 决策记录（ADR），保持规范与代码同步。
规范纳入 Git + Review：规范随 PR 流转，像代码一样被评审和 Diff，避免脱节。

9. 参考链接

GitHub Spec Kit（开源工具包）：https://github.com/github/spec-kit
Microsoft for Developers — Diving Into Spec-Driven Development With GitHub Spec Kit：https://developer.microsoft.com/blog/spec-driven-development-spec-kit
Microsoft for Developers — Spec-Driven Development: A Spec-First Approach to AI-Native Engineering：https://developer.microsoft.com/blog/spec-driven-development-ai-native-engineering
Martin Fowler — Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl：https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
Augment Code — Vibe Coding vs Spec-Driven Development (2026)：https://www.augmentcode.com/guides/vibe-coding-vs-spec-driven-development
Augment Code — What Is Spec-Driven Development? A Complete Guide：https://www.augmentcode.com/guides/what-is-spec-driven-development
Augment Code — 6 Best Spec-Driven Development Tools for AI Coding in 2026：https://www.augmentcode.com/tools/best-spec-driven-development-tools
Towards Data Science — From Vibe Coding to Spec-Driven Development：https://towardsdatascience.com/from-vibe-coding-to-spec-driven-development/
Turing Post — Spec-Driven Development vs Vibe Coding: Tools & Guide (2026)：https://www.turingpost.com/p/sdd
Microsoft Community Hub — An AI led SDLC（内/外环、Harness）：https://techcommunity.microsoft.com/blog/appsonazureblog/an-ai-led-sdlc-building-an-end-to-end-agentic-software-development-lifecycle-wit/4491896
ideaplan.io — The AI SDLC（三环模型）：https://www.ideaplan.io/guides/ai-sdlc-product-management-2026
Medium（Guangya Liu）— Code is Cheap, Show Me the Markdown：https://gyliu513.medium.com/code-is-cheap-show-me-the-markdown-070db56f5048
Medium（Vishal Mysore）— SDD Is Eating Software Engineering：https://medium.com/@visrow/spec-driven-development-is-eating-software-engineering-a-map-of-30-agentic-coding-frameworks-6ac0b5e2b484
博客园（深蓝）— 规范驱动开发深入解析：https://www.cnblogs.com/studyzy/p/19638317
Microsoft Learn（中文）— 规范驱动开发与 GitHub Spec Kit 入门：https://learn.microsoft.com/zh-cn/training/modules/spec-driven-development-github-spec-kit-greenfield-intro/
微信公众号文章（用户提供参考）：https://mp.weixin.qq.com/s/aAH2pev1UJzEK4qmZM9JoA