Spec-Driven Development (SDD) 最佳工程实践

Chapter 01

什么是规格驱动开发 (SDD)

从“Prompt 即代码”的混乱（Vibe Coding）走向严谨的规格驱动体系

💡 一句话理解

Spec-Driven Development (SDD) 是一种以正式、结构化的规格文件（Specification）作为第一真相来源的开发模式。所有的代码生成、技术设计与测试验证均紧密锚定规格，而不是随意的自然语言会话。

为什么 "Vibe Coding" 在生产中行不通？

在 2025 年夏季，以随意 prompting、不断接受 AI 产出代码为特点的 "Vibe Coding" 風靡一时。然而到了 2026 年，企业在将其应用于生产系统时发现了三大致命痛点：

🧠

上下文腐烂 (Context Rot)

随着对话不断加长，LLM 逐渐遗忘前期的架构设计和核心变量定义，代码库开始出现架构分裂。

📈

架构漂移 (Architectural Drift)

AI 倾向于为了解决局部的 Bug 引入新的依赖或者打破既有的三层分层设计，导致项目愈加混乱。

🚨

静默故障 (Silent Failures)

缺乏规范 of 测试合规校验，AI 生成的代码表面上编译通过，实则在边界条件和安全漏洞上埋下了隐患。

🔑 2026 年行业新共识：规划才是新编码

AI 在写具体代码（如写 CRUD、写正则）方面已超越绝大部分初级开发者，但 AI 很难理解未明确表述的人类意图。因此，软件工程师的瓶颈已从 "编写代码" 转向 "设计精确的规格（Spec）和验证体系" 上。

SDD vs. Vibe Coding 全维度对比

维度	Vibe Coding（临时提示）	Spec-Driven Development
驱动力	自然语言提示	正式规格文档
真相来源	AI 上下文记忆	`spec.md` / `openapi.yaml`
一致性	随对话漂移	规格锚定，不漂移
可验证性	靠人眼审查	自动合规测试
协作方式	单人 prompting	团队共享规格合约
适合场景	原型 / 探索	生产级 / 企业级系统

✅ 2026 年共识

Vibe Coding 适合原型探索，SDD 适合生产交付。两者互补而非对立——很多团队在早期探索阶段用 Vibe Coding 快速验证想法，一旦进入生产交付就切换到 SDD 纪律。

Chapter 02

SDD 的三大核心原则

如何确立 AI 代理的可控性与确定性？

Principle 01

规格为本 (Spec-as-Source)

任何功能需求必须先以格式化（如 Markdown / OpenAPI）记录在规格文件中。代码仅是规格的一种具体实现或“编译产物”。规格变更必须在代码修改之前完成。

Principle 02

先规划后动笔 (Plan-Before-Code)

严禁 AI 盲目跳入代码修改。在任何实现任务前，AI 必须基于规格生成一份详细的《技术实现蓝图》和《原子化任务拆解清单》，待人工审核通过方可动工。

Principle 03

证据验证 (Evidence-Required)

每一个原子任务在被标记为“已完成”前，AI 必须提交能够证明其工作正确的具体凭证。这可以是单元测试通过报告、接口响应日志、甚至 UI 测试截图。

核心工具：项目宪法 (Project Constitution)

在基于 SDD 的工程库中，一般会在根目录或配置目录下定义一份项目宪法（如 constitution.md 或 CLAUDE.md）。该文件用作系统级 Prompt 喂给 AI，定义不可违反的绝对规则。

# Project Constitution - bookmark-api

## Principles
1. Spec is the source of truth. Do not implement code not declared in spec.md.
2. Maintain high test-driven quality: new features must have >85% unit test coverage.

## Tech Stack (Non-Negotiable)
- Python 3.11+
- FastAPI (as router framework)
- SQLite (for local development database)

## Forbidden Actions
- Do NOT add external dependencies without modifying requirements.txt.
- Do NOT change files outside the 'Allowed Files' listed in tasks.md.

Chapter 03

SDD 的四阶段生命周期

从意图设计到自动化合规测试的完整工作流闭环

1. SPECIFY (规格化)

定义功能和意图。使用 EARS 语法书写需求。限制 Non-Goals（非目标）防止开发漂移。

→

2. PLAN (规划)

技术架构设计、表模型、接口设计。产出原子化 tasks.md 并指定文件白名单。

→

3. IMPLEMENT (实现)

AI 自动生成代码。受到任务清单的文件级权限沙箱约束，确保不会越界。

→

4. VALIDATE (验证)

自动化单元测试与 OpenAPI 契约测试合规验证，不合规时回退重试。

Specify 阶段的 EARS 需求语法

为了能够让 AI 100% 精准理解和提取测试验收用例（Acceptance Criteria），我们一般在 spec.md 中使用 EARS (Easy Approach to Requirements Syntax) 句式编写功能点：

EARS 核心结构

WHEN [前置事件/触发条件], THE SYSTEM SHALL [系统的行为和预期反应]

例：WHEN the user requests bookmarks with a specific tag, THE SYSTEM SHALL return only the bookmarks containing that tag (case-insensitive).

Chapter 04

四大主流 SDD 落地框架

2026 年主流开发团队的落地方案对比：从 Agentic IDE 到 API 契约标准

1. GitHub Spec Kit

GitHub 开源 / Agent 无关

通过 .specify/ 统一规范模板。不绑定任何大模型。最轻量，可在 Claude Code、Gemini CLI 等开发流中任意组装。

核心文件：constitution.md
安全控制：Allowed Files 白名单限制
验证机制：证据依赖任务完成标志

2. BMAD Method

开源方法论 / 多智能体编排

强调多角色（PM, Architect, Scrum, Dev, QA, Ops）的分离和互相审查。基于完整严谨的“制品链”开发。

核心文件：prd.md, architecture.md
安全控制：模型间多对多交叉评审
验证机制：QA Agent 生成 AC 追溯矩阵

3. AWS Kiro

AWS 专有 / 深度 IDE 集成

将 SDD 工作流嵌入 IDE 界面的闭源编辑器。能够直接编译云端资源并验证云架构合规。

核心文件：requirements.md, design.md
安全控制：内置 AWS 资源安全扫描
验证机制：结合 AWS CDK 运行测试

4. OpenAPI / Open Spec

行业标准 / 契约先行（Contract-First）

SDD 在 API 层的具象化实现：先设计 openapi.yaml 契约，再生成 Mock、代码与文档，契约即真相来源。

核心文件：openapi.yaml / asyncapi.yaml
安全控制：Spectral Lint + Schemathesis 契约测试
验证机制：Prism Mock + 自动合规回归

契约先行工作流（Contract-First Workflow）

1. Design

编写 openapi.yaml 契约

→

2. Review

团队共识评审

→

3. Mock

Prism / Stoplight 拉起 Mock

→

4. Build

生成 SDK + 实现服务端

→

5. Validate

Schemathesis 契约测试

→

6. Publish

Swagger UI / ReDoc 文档

四大方案横向对比

维度	Kiro	BMAD	Spec Kit	OpenAPI
定位	Agentic IDE	多 Agent 框架	SDD 工具套件	API 契约标准
真相来源	requirements.md	prd.md	spec.md	openapi.yaml
Agent 绑定	Kiro 内置	Claude / Cursor	任意 Agent	任意工具
角色模拟	❌ 无	✅ 6+ 角色	❌ 无	❌ 无
Constitution	steering/	CLAUDE.md	constitution.md	❌ 无
Mock 支持	❌	❌	❌	✅ Prism
契约测试	❌	❌	证据驱动	✅ Schemathesis
学习曲线	低	中	低	中
适合规模	中大型	大型	小中大型	API 项目

工具选型矩阵

场景	推荐工具	理由
企业级新项目（Greenfield）	Kiro	强制 SDD 流程，AWS 生态集成
已有项目 + Claude/Cursor	BMAD Method	多 Agent 角色模拟，可嵌入现有工作流
Agent 无关 + 轻量 SDD	Spec Kit ⭐	官方出品，无供应商锁定，模板标准化
API-First / 微服务	OpenAPI + Prism	行业标准，工具链成熟，Mock 支持好
轻量个人项目	手写 SPEC.md + AGENTS.md	80% 收益，零工具依赖

💡 选型建议

对于大部分常规的云原生和微服务团队，推荐首选 GitHub Spec Kit 模式。其轻量级设计不破坏原有的 CI/CD 流程，通过简单的 Markdown 文件即可在 Git 中实现规格版本化；若项目以 API 为核心交付物，则应叠加 OpenAPI 契约先行作为补充。

Chapter 05

SDD 成熟度模型与团队选型

四级成熟度模型：多数团队的合理目标是 L2

等级	名称	说明	适用场景
L1	Spec-First	人写规格 → AI 生成代码（单次会话）	原型、脚本
L2	Spec-Anchored ⭐	规格与代码同步演进，CI/CD 强制合规	生产系统（推荐）
L3	Spec-as-Source	人只编辑规格，代码完全由 Agent 生成/再生成	高度标准化系统
L4	Spec-to-Application	规格由确定性编译器（非 LLM）翻译为代码	安全关键系统

📐 ThoughtWorks 技术雷达建议

ThoughtWorks 技术雷达 Vol.34 建议大多数团队目标为 L2（Spec-Anchored）——规格与代码的"活文档"协同，既保留人工可控性，又能享受 AI 生成代码的效率红利。

Chapter 06

企业级 SDD 最佳工程实践

如何在真实项目中落地以降低 AI 犯错率

实践 1：任务级别的允许修改文件白名单 (Allowed Files)

大模型在做大型工程修改时，常因为联想过度而“污染”不相关的模块。在编写 tasks.md 时，对于每一个 task 必须明确定义仅允许修改的文件路径，从底层机制上杜绝 AI 乱改代码。

## Task 3: 实现数据库存储与 migrations
- **目标**: 新建 Bookmark 实体表并添加 migration 文件。
- **允许修改的文件**:
  - `src/models/bookmark.py`
  - `src/models/__init__.py`
- **验证方式**: 运行 `alembic upgrade head` 不报错且生成 test.db。

实践 2：结合 OpenAPI 设计契约测试 (Contract First)

在 SDD API 设计中，接口是前后台或者多微服务间的首要契约。在开发逻辑前先编写 openapi.yaml。

使用 Spectral 对 openapi.yaml 进行规范静态扫描。
使用 Prism 一键拉起 Mock 服务，使前端可以并行开发。
在 CI 流程中使用 Schemathesis 自动读取 openapi 规范，模拟百个异常请求对服务端进行合规性攻击测试，保障零规范违背。

实践 3：持续演进的活制品策略 (Living Artifact)

切忌把 spec.md 当作"一次性文档"。若在开发过程中发现系统有不可抗拒的设计缺陷，必须 "规格先改 -> Review 合格 -> 代码跟进"，而不是越过规格直接在代码里开倒车。

实践 4：自动化验证清单（CI Gate）

使用 EARS 语法书写需求：WHEN [事件] THE SYSTEM SHALL [行为]，每条需求可独立验证
单个 feature 的 spec 长度控制在 500 行以内，超出即拆分
明确定义 Non-Goals / Out of Scope，防止范围蔓延
每个阶段边界（规格→计划→代码）须人工确认，不可跳过 Human Gate
CI 管道中加入 OpenAPI 合规检查（Spectral lint）与契约测试（Schemathesis）
每个 task 完成后需附带证据（test pass / log），并在 tasks.md 中引用对应需求 ID

Chapter 07

行业采用趋势（2024–2026）

从 Vibe Coding 之夏到 ThoughtWorks Adopt 象限

时间	里程碑事件
2024 Q3	Andrej Karpathy 提出 "Vibe Coding" 概念，AI 编程进入大众视野
2025 Q1	ThoughtWorks 技术雷达 Vol.32：SDD 进入 Trial 象限
2025 Q2	AWS Kiro 发布，首个内置 SDD 工作流的 Agentic IDE
2025 Q3	BMAD Method v6 开源，多 Agent 角色模拟成为热门方案
2025 Q4	GitHub Spec Kit 开源，成为 Agent 无关 SDD 的参考实现
2025 Q4	OpenAPI 3.1 全面对齐 JSON Schema，成为 AI Agent 消费 API 的事实标准
2026 Q1	GitHub Copilot 集成 "Spec Mode" 到 Enterprise 版本
2026 Q2	ThoughtWorks 技术雷达 Vol.34：SDD 升级为 Adopt 象限 ⬆️
2026 Q2	ThoughtWorks 发布 Agent/works™ 平台，解决企业级 Agent 治理
2026 H1	AI 编码 Agent 市场规模突破 $10B+/年

"Vibe Coding 之夏"的终结

2025 年的 Vibe Coding 热潮证明了 AI 编码的速度优势，但在企业级场景暴露了致命缺陷：

Vibe Coding 失败模式	SDD 如何解决
上下文腐烂（Context Rot）	规格文件锚定意图，不依赖会话记忆
架构漂移（Architectural Drift）	Constitution / AGENTS.md 约束不可违反
静默故障（Silent Failures）	证据驱动验证，每个 task 须附带测试通过证据
代码不可维护	代码是规格的派生物，可追溯、可重生成

工程师角色演变

2024

工程师 = 代码作者（Author）

→

2025

工程师 = AI 提示师（Prompter）→ Vibe Coding

→

2026

工程师 = 意图设计师 + Agent 编排师

⚠️ 2026 年关键风险

认知负债：AI 生成的代码量超过人类理解能力，导致系统"无人真正理解"。Agent 蔓延：企业部署过多 Agent 缺乏统一治理，权限失控。语义扩散："SDD"、"Agentic" 等术语定义未稳定，各家实现差异大。

Chapter 08

未来趋势预判（2027–2030）

从 Spec-Anchored 到 Spec-to-Application 的技术演进路线图

趋势 1：Spec-as-Source（2027）

人只编辑规格，代码完全由 Agent 生成，PR 由 Agent 自动生成和自动 Review。代码不再被"拥有"，而是被"生成和验证"。

趋势 2：多 Agent 编排成为标配（2027）

Gartner 预测到 2027 年 65%+ 使用 Agentic 编码的团队将视传统 IDE 为可选。Manager-Worker 架构下，Agent 间的"契约"本身也需要规格化。

趋势 3：自愈代码系统（2027–2028）

Monitor → Diagnosis → Fix → Verify 闭环，因果记忆识别重复故障模式，修复成功后自动反馈更新 Spec，DevOps 演变为 "SpecOps"。

趋势 4：形式化验证民主化（2027–2028）

神经符号系统（Neuro-symbolic）崛起：LLM 生成灵活性 + 符号求解器逻辑严谨性组合，"证明"与"测试"并行成为 QA 标准工具。

趋势 5：DSL 复兴与规格语言标准化（2028–2029）

Markdown 语义模糊的问题推动演进路径：Markdown → 结构化 YAML/JSON Schema → 专用 DSL → 确定性编译器（L4）。

趋势 6：组织与人才结构重塑（2027–2030）

3 人团队 + AI Agent 编排 = 过去 30 人团队的交付能力。瓶颈从"写代码"转移到"定义意图"和"验证质量"。

未来 SDD 成熟度演进总览

时间	成熟度	人的角色	代码的定位	验证方式
2025	L1 Spec-First	写代码 + 写规格	主要产物	测试
2026	L2 Spec-Anchored	写规格 + 审代码	对等产物	测试 + 契约
2027	L3 Spec-as-Source	只写规格	派生产物	测试 + 形式化
2028	L3.5 Self-Healing	审规格 + 审修复	自愈产物	自动证明
2029-30	L4 Spec-to-App	审规格	编译产物	数学证明

🎯 给工程师的行动建议

1. 立即开始练习写规格（spec.md / constitution.md），这是未来最核心的工程技能。2. 学习多 Agent 编排，理解 Agent 间的协作和治理模式。3. 了解形式化方法基础（前/后置条件、不变量），不需要成为专家，但需要能审查。4. 培养领域建模能力，将业务知识转化为结构化规格。

Chapter 09

配套 Demo 项目

三个可直接运行和对比的完整工作流实现

Demo 1：Kiro 风格 SDD（Todo API）

27 tests passed ✅

.kiro/specs/todo-api/   # EARS需求+设计+任务
openapi.yaml            # API 契约
src/                    # FastAPI 实现
tests/                  # 契约+功能测试

Demo 2：BMAD Method（FinTrack）

30 tests passed ✅

.bmad/agents/           # 6个Agent Persona
docs/                   # brief→PRD→arch→stories
src/                    # FastAPI 实现
tests/                  # AC追溯测试+QA报告

Demo 3：Spec Kit（Bookmark API）⭐

17 tests passed ✅

.specify/memory/constitution.md
.specify/specs/bookmark-crud/
src/                    # FastAPI 实现
tests/                  # 证据驱动测试

📦 说明

三个 Demo 分别演示了 Kiro、BMAD、Spec Kit 三种 SDD 方案的完整工作流，覆盖需求-规划-实现-验证全流程，可直接运行和横向对比。

Chapter 10

SDD 面试宝典与核心考点

备战 AI 软件工程专家、AI 架构师面试必备技能

Q1: SDD 模式和传统的测试驱动开发（TDD）有什么异同与联系？

相同点: 都是先于“真正写逻辑代码”前设计验证标准，都追求极高的可测试性与纪律性。

不同点: TDD 的入口是具体的编程单元测试（代码）；而 SDD 的入口是更具业务属性、描述意图的规格文档（Spec）。在 AI 时代，由于代码可以由 Agent 从 Spec 中自动推导和重生成，SDD 的层级比 TDD 更高，TDD 只是 SDD “Validate” 阶段的一部分。

Q2: 如何在大模型多阶段对话（Specify -> Plan -> Code）中防范上下文丢失（Context Loss）？

1. 制品锚定法: 在每一个阶段开头，显式地要求 Agent 加载并全文读取 constitution.md 和 spec.md。

2. 单向只读性: 限制除 Specify 阶段外的 Agent 去修改 spec.md。将 spec 文件视为恒定参考，代码 and plan 只能引用，不能写回（除非有明确的进化指令）。

3. 重构对话: 实现新的 feature 时，应当另起一轮全新的干净对话，仅挂载最新的 spec 文件和已有的代码库，这可以过滤掉历史讨论对 AI 上下文产生的垃圾噪声。

Q3: 在 Agent 越界修改了白名单之外的文件时，在合规性设计上应如何防护？

1. Git 合规门禁 (CI Gate): 在 Git Pre-commit 钩子或 CI 流水线中运行脚本，对比 tasks.md 的白名单和 git diff --name-only 的输出，如果不一致直接中止提交并触发报警。

2. Harness 文件系统沙箱 (Sandbox): 在支持虚拟化的容器或只读挂载卷中运行 Dev Agent，仅提供 Allowed Files 列表对应路径的写权限，让 AI 即使写错代码也会被操作系统层拦截，彻底隔离安全风险。

Q4: 什么是 SDD 成熟度模型？大部分团队应该以哪一级为目标？

SDD 成熟度分四级：L1 Spec-First（人写规格，AI 单次生成代码，适合原型）；L2 Spec-Anchored（规格与代码同步演进，CI/CD 强制合规，适合生产系统）；L3 Spec-as-Source（人只编辑规格，代码完全由 Agent 生成/再生成）；L4 Spec-to-Application（规格由确定性编译器而非 LLM 翻译为代码，适合安全关键系统）。ThoughtWorks 技术雷达建议大多数团队的合理目标是 L2，在可控性与效率之间取得平衡。

Q5: OpenAPI 契约先行和 Spec Kit 的 spec.md 是什么关系？能否同时使用？

二者不是竞争关系，而是不同层级的 SDD 实现：Spec Kit 的 spec.md/plan.md 面向整个功能（业务需求、架构设计、任务拆解），而 openapi.yaml 专注于 API 契约层（请求/响应 Schema、状态码、鉴权方式）。在实践中，团队常常在 Spec Kit 的 plan.md 中直接引用或内嵌 OpenAPI 定义作为接口设计的权威来源，并用 Schemathesis 等工具对实现做契约测试，这样两套体系可以无缝叠加使用。

规格驱动开发AI 时代的软件开发新纪律