Spec Kit 中的规范驱动开发（SDD）：从"代码为王"到可执行规范的方法与实践

Spec-Driven Development（SDD，规范驱动开发）是 Spec Kit 项目的核心方法论。本文基于仓库文档 docs/concepts/sdd.md 展开，系统讲解 SDD 的核心理念、三大开发阶段与实验目标，并结合仓库中的规范模板、命令流程与工作流配置，说明"规范成为可执行产物"这一理念在 Spec Kit 中的具体落地方式。读完本文，你不仅能理解 SDD 与传统开发范式的区别，还能掌握在 Spec Kit 项目中完整运行 规范 → 计划 → 任务 → 实现 流程的实操路径。

一、SDD 的核心主张：翻转"代码为王"的传统

Spec Kit 文档的开篇就点明了 SDD 与传统软件开发的关系：翻转了剧本（flips the script）。几十年来，代码一直是王者——规范只是"脚手架"，一旦真正的编码工作开始，它们就被抛弃。SDD 改变了这一点：规范成为可执行的（specifications become executable），直接生成可用的实现，而不仅仅是指导实现。

仓库中更完整的论述见 spec-driven.md，其中提出了"权力反转"（Power Inversion）的框架：

• 规范不再是代码的仆从：PRD 不是实现指南，而是生成实现的源头；技术计划不是告知编码的文档，而是产生代码的精确定义。
• 消除规范与实现之间的鸿沟：传统的"文档-代码不一致"问题被消除，因为规范与实现计划本身就生成代码——"没有鸿沟，只有转换（no gap—only transformation）"。
• 自然语言成为开发的第一语言（lingua franca）：开发团队的意图用自然语言表达（即"意图驱动开发"），设计资产、核心原则与指南构成开发语言，代码退居为"最后一公里"的实现形式。
• 维护软件 = 演化规范：调试意味着修正生成错误代码的规范与计划；重构意味着为清晰度而重新组织；新增功能意味着回到规范再创建新的实现计划。

这一理念之所以"现在可行"，前提是 AI 模型能够理解和实现复杂规范并制定详细实现计划；而 SDD 的价值恰恰在于为这种原始生成能力提供结构——通过精确、完整、无歧义的规范与计划来约束和引导生成过程。

SDD 作为结构化过程的四个特征

sdd.md 将 SDD 定义为一个结构化过程，强调四点：

1. 意图驱动开发（Intent-driven development）：规范先定义"做什么"（what），再讨论"怎么做"（how）；
2. 丰富的规范创建：借助护栏（guardrails）和组织原则来产出高质量规范；
3. 多步精炼（Multi-step refinement）：而非从提示词一次性生成代码；
4. 重度依赖先进 AI 模型能力：用于规范的解释与实现。

这四点在 Spec Kit 中有直接的工程对应：第 1 点由规范模板强制（下文详述）；第 2 点对应项目"宪法"（constitution）机制；第 3 点体现为 Specify → Plan → Tasks → Implement 的多阶段命令流；第 4 点则是整个工具链的运行前提。

二、三大开发阶段：Greenfield、探索与 Brownfield

sdd.md 将 SDD 的应用划分为三个开发阶段，这一划分同样出现在项目 README 中，是理解 SDD 适用边界的关键表格：

阶段	聚焦	关键活动
0-to-1 开发（"Greenfield"，绿地）	从零生成	从高层需求开始；生成规范；规划实现步骤；构建生产就绪的应用
创意探索（Creative Exploration）	并行实现	探索多样化解决方案；支持多种技术栈与架构；实验 UX 模式
迭代增强（"Brownfield"，棕地）	棕地现代化	迭代式添加功能；现代化遗留系统；适配流程

三个阶段分别对应不同的使用姿态：

• 绿地场景是最直接的 0→1 场景：从一句高层需求描述出发，经 SDD 流程生成生产级应用。这也是 docs/quickstart.md 中以 Taskify 项目为例演示的完整路径。
• 创意探索是 SDD 区别于"规范-实现流水线"的独有能力：同一份规范可以派生出多份不同技术栈、不同架构、不同 UX 模式的并行实现。仓库中 spec-driven.md 将其概括为"Branching for Exploration"——从同一规范生成多种实现方案，分别针对性能、可维护性、用户体验、成本等不同优化目标进行探索。
• 棕地场景关注存量项目。README 中特别指出：在既有项目中，应将 Spec Kit 工具链的升级与 specs/ 下功能产物的演化分开处理——升级工具链时刷新受管理的项目文件，当预期行为变化时更新规范产物。推荐流程详见 docs/guides/evolving-specs.md。

三、实验目标：验证 SDD 的普适性边界

sdd.md 明确说明 Spec Kit 仍处于研究与实验阶段，实验聚焦四个方向：

3.1 技术独立性（Technology Independence）

• 使用多样化的技术栈创建应用；
• 验证一个核心假设：SDD 是一种与具体技术、编程语言或框架解耦的过程。

这一点与规范模板的约束直接相关——规范阶段被禁止出现技术栈内容（见第五节），正是为了保证同一份 spec.md 可以被翻译成任意技术实现。

3.2 企业约束（Enterprise Constraints）

• 演示关键任务（mission-critical）应用的开发；
• 纳入组织级约束：云服务商、技术栈选择、工程实践；
• 支持企业设计系统与合规要求。

3.3 以用户为中心的开发（User-Centric Development）

• 面向不同用户群体和偏好构建应用；
• 支持多种开发方式——从"vibe-coding"到 AI 原生开发。

3.4 创意与迭代过程（Creative & Iterative Processes）

• 验证并行实现探索的概念；
• 提供健壮的迭代式功能开发工作流；
• 将流程扩展到升级与现代化任务。

这四个目标与"三大开发阶段"形成呼应：技术独立性支撑创意探索，企业约束支撑棕地现代化，而创意与迭代过程则覆盖从绿地到棕地的完整生命周期。

四、"可执行规范"在 Spec Kit 中的落地：命令流程与产物链

SDD 的"规范可执行"不是空谈——在 Spec Kit 中，它体现为一条由斜杠命令驱动、每一步都产出结构化 Markdown 产物的流水线。每个阶段的产物直接作为下一阶段的输入，让 AI 编码代理获得的是结构化上下文而非临时提示词。

4.1 完整命令序列

来自 docs/reference/agentic-sdd.md 的标准序列：

/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan -> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement -> /speckit.converge

其中只有 /speckit.specify 是 /speckit.plan 之前的硬性前置；clarify、checklist、analyze 是针对存在实质模糊性内容的质量门。最小路径（小型功能）为四步加收敛：

/speckit.specify -> /speckit.plan -> /speckit.tasks -> /speckit.implement -> /speckit.converge

各命令职责（摘要自 docs/quickstart.md 与 docs/reference/agentic-sdd.md）：

命令	职责	关键产物
/speckit.constitution	一次性确立项目治理原则，后续每个阶段都以其为评估基线	项目宪法（constitution）
/speckit.specify	从自然语言描述生成功能规范，聚焦 what/why，不谈技术栈	spec.md（含用户故事、验收场景、FR 需求、成功标准）
/speckit.clarify	就规范中欠定义的部分提出最多 5 个针对性问题，并将答案写回规范	更新后的 spec.md
/speckit.plan	提供技术栈与架构选择，生成设计产物	plan.md、data-model.md、contracts/、research.md、quickstart.md
/speckit.checklist	为规范生成质量检查清单——"针对需求的单元测试"	自定义检查清单
/speckit.tasks	从设计产物派生依赖有序的任务清单	tasks.md（按 Setup / Foundational / 每用户故事一阶段 / Polish 组织，并行任务标 [P]）
/speckit.analyze	只读的跨产物一致性分析，报告冲突、缺口与歧义	分析报告（不修改任何文件）
/speckit.implement	按依赖顺序执行 tasks.md 中的任务，尊重并行标记	实现代码
/speckit.converge	将代码库对照规范、计划、任务做缺口评估，仅追加新任务到 tasks.md	收敛报告或追加任务

注意 /speckit.converge 的收敛循环设计：它先输出按严重度分级的发现摘要，然后给出两种结局——Converged（无缺口，tasks.md 字节级不变）或 Tasks appended（发现缺口，追加为新任务）。官方建议反复执行 implement + converge，直到 converge 报告收敛。这个"实现→校验→补任务→再实现"的闭环，正是 SDD"多步精炼而非一次性生成"原则在实现阶段的体现。

4.2 工作流编排：全流程自动化

除了逐条手动执行命令，Spec Kit 还支持将整条 SDD 流程编排为工作流。仓库内置的 workflows/speckit/workflow.yml 就是一个示例——它声明了 specify → plan → tasks → implement 四个步骤，并在规范与计划之后各插入一个人工审查门（gate）：

description: "Runs specify → plan → tasks → implement with review gates"
requires:
  speckit_version: ">=0.8.5"
inputs:
  spec:
    type: string
    required: true
    prompt: "Describe what you want to build"
  integration:
    type: string
    default: "auto"

从该配置可以看出两个 SDD 的实践要点：其一，review-spec 与 review-plan 两个 gate 说明人在关键节点介入审查是流程的一等公民——规范质量门不能省；其二，speckit_version: ">=0.8.5" 的声明说明工作流对 CLI 版本能力有明确前提（该版本起才支持 integration: "auto" 的引擎端解析）。这也提示读者：引用命令或工作流时，以当前安装版本的实际能力为准。

4.3 产物链的目录形态

以 spec-driven.md 中的聊天功能示例为例，一次完整运行后功能目录下会形成如下产物结构：

specs/003-chat-system/
├── spec.md            # 功能规范：用户故事 + 验收标准
├── plan.md            # 实现计划：技术选型与理由
├── research.md        # 研究笔记（如 WebSocket 库对比）
├── data-model.md      # 数据模型（Message、User 模式）
├── contracts/         # API 契约（WebSocket 事件、REST 端点）
├── quickstart.md      # 关键验证场景
└── tasks.md           # 派生出的可执行任务列表

文档给出的对比很直观：传统方式写 PRD、设计文档、技术规格、测试计划约需 12 小时文档工作；SDD 命令路径下 15 分钟内即可完成"完整功能规范 + 实现计划 + API 契约与数据模型 + 测试场景 + 版本化的特性分支"。

五、模板约束：SDD 如何把 LLM 变成"有纪律的规范工程师"

SDD 的"丰富规范创建"并非靠运气。spec-driven.md 专门有一节解释模板如何约束 LLM 行为，而约束的实体就在仓库 templates/ 目录中：

• templates/spec-template.md：规范模板；
• templates/plan-template.md：计划模板；
• templates/tasks-template.md：任务模板；
• templates/constitution-template.md：宪法模板；
• templates/commands/：各斜杠命令的提示词文件（如 specify.md、implement.md）。

具体约束机制包括：

1. 防止过早实现细节：规范模板明确指示"聚焦用户需要什么与为什么（✅ WHAT/WHY），避免如何实现（❌ 不写技术栈、API、代码结构）"。这把抽象层次固定在规范阶段，使同一份规范可以映射到不同技术栈——正是 SDD"技术独立性"目标的模板级保障。

2. 强制显式的不确定性标记：模板要求对所有模糊点使用 [NEEDS CLARIFICATION: 具体问题] 标记且不许猜测。spec-template.md 中给出了标准示例：

   - **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
   

3. 检查清单作为规范的"单元测试"：模板内嵌"需求完整性/成功标准可度量"等检查清单，强制 LLM 系统性自查。功能需求使用 FR-001 编号、用户故事按 P1/P2/P3 优先级排序且要求每个故事可独立测试（单独实现也能交付可运行的 MVP），这些结构都直接定义在 templates/spec-template.md 中。

4. 宪法门（Constitutional Gates）反制过度设计：实现计划模板包含"Phase -1 前置门"，如"简单性门（是否 ≤3 个项目？无未来化设计？）""反抽象门（是否直接用框架？单一模型表示？）"。门不通过时，LLM 必须在"复杂性追踪"部分书面论证——架构决策因此有了问责机制。

5. 测试先行：计划模板强制"先建 contracts/ 契约、再按 contract → integration → e2e → unit 顺序建测试、最后写源码使测试通过"的文件创建顺序。

6. 禁止臆测功能：模板检查项明确"无投机性或'可能需要'的功能"，每个功能必须能追溯到具体用户故事。

宪法机制的模板是 templates/constitution-template.md：它预置了"库优先、CLI 接口、测试先行、集成测试、可观测性、版本化、简单性"等原则槽位与治理条款，同时保留 [SECTION_2_NAME]、[SECTION_3_NAME] 等占位符——即九章结构中部分条款刻意留给各项目按自身组织标准定义，/speckit.constitution 命令会依据传入的原则参数填充并生成项目宪法，后续各阶段命令都以它为合规基线。

多步精炼的工程价值

把上述模板机制合起来看，就得到了 SDD"多步精炼"的完整解释：每一步产出的产物都被模板约束为结构化、可校验、可追溯的形态——需求可追溯到用户故事（FR 编号 ↔ 任务 ↔ 契约），技术决策可追溯至需求，架构复杂度必须有书面论证。/speckit.analyze 的跨产物一致性检查（例如"某任务没有对应需求"这类报告项）则在这条产物链之上做持续校验，而非一次性门禁。

六、规范的生命周期：三种持久化模型

sdd.md 明确声明：Spec Kit 不规定需求变化后团队如何保存或变更 spec.md、plan.md、tasks.md——它提供可重复的工作流，但把产物维护策略的选择权留给团队。相关概念完整论述见 docs/concepts/spec-persistence.md，该页命名了三种常见模型（均非默认值、均非强制）：

模型	变更规则	最适场景	需警惕
Flow-back spec（回流式）	可编辑任意产物，事后人工协调	小团队、快速迭代、实现中发现会重塑原计划	产物间静默漂移——下层产物的决策未回流到 spec.md，后人不知该信哪份
Flow-forward spec（前向式）	需求变更时新建功能目录，旧产物视为不可变历史	可审计性、可追溯性优先	相关决策分散在多个功能目录中，产生重复与上下文碎片化
Living spec（活规范）	spec.md 是契约，先改它再重新生成/修订 plan.md 与 tasks.md	产品契约足够稳定、团队接受派生产物的再生成	派生物被丢弃时可能丢失实现层面的重要论证

该页还指出 SDD 隐含两个独立问题，团队选择模型时应分别回答：

1. 完成的功能目录应当是历史记录还是可编辑的工作区？
2. spec.md 是单一事实源，还是允许 plan.md、tasks.md 成为共同事实源？

一旦回答清楚，建议把该约定写入项目宪法或团队 onboarding 文档，让后来的贡献者知道如何处理变更。对于存量项目，棕地演化循环（何时升级工具链、何时更新规范产物）见 docs/guides/evolving-specs.md；针对既有代码库安全引入 Spec Kit 的步骤见 docs/guides/existing-projects.md。

七、快速上手：把 SDD 跑起来

以上理念最终都要落到执行。以下是最短可运行路径（完整分步见 docs/quickstart.md，安装方式见 docs/installation.md，环境要求为 Linux/macOS/Windows、Python 3.11+、Git、uv 或 pipx）：

# 1. 安装 CLI（从 PyPI）
uv tool install specify-cli

# 2. 初始化项目并选择编码代理（30+ 集成，如 copilot / claude / gemini / codex）
specify init my-project --integration copilot
cd my-project

然后在项目目录启动你的编码代理，依次执行：

# 一次性：确立项目原则
/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

# 1. 规范：只描述 what/why
/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page.

# 2. 计划：给出技术栈与架构
/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Metadata is stored in a local SQLite database.

# 3. 任务分解
/speckit.tasks

# 4. 实现（大型功能可按阶段限定范围，例如：
#    /speckit.implement only execute tasks T001-T010, then stop and report progress）
/speckit.implement

# 5. 收敛校验，重复 4/5 直到报告 Converged
/speckit.converge

两点适用前提与限制：其一，命令的具体调用形式因代理而异——多数代理以 /speckit.* 斜杠命令暴露，Codex CLI、Command Code 的 skills 模式使用 $speckit-*，Kimi 使用 /skill:speckit-*，以你的代理实际暴露的形式为准；其二，大型功能的长实现会遭遇上下文窗口耗尽问题，docs/concepts/complex-features.md 给出了四个应对策略：按任务/阶段限定单次运行范围、指示代理用子代理委派并行 [P] 任务、两者结合、以及把超大功能分解为多个独立子规范（"spec of specs"，见 docs/concepts/spec-of-specs.md）。

八、结语：规范成为事实源，代码成为其表达

回到 sdd.md 的核心命题：SDD 把"规范是脚手架"的传统翻转成"规范是可执行的事实源"。Spec Kit 对这一理念的实现可以归纳为三层证据链——

• 流程层：Specify → Plan → Tasks → Implement → Converge 的多步精炼命令流，产物逐级派生、/speckit.analyze 做跨产物一致性校验，保证"生成"而非"拼凑"；
• 约束层：规范/计划/宪法模板以 WHAT/WHY 分离、[NEEDS CLARIFICATION] 标记、架构门、测试先行等机制约束 LLM 输出，让规范精确到可执行；
• 策略层：三大开发阶段（绿地/创意探索/棕地）界定适用边界，三种规范持久化模型（flow-back / flow-forward / living）把产物生命周期决策权显式交还团队。

理解这三层，你就不仅会跑 SDD 命令，还能回答"什么场景该用 SDD、规范产物该怎么维护、如何防止 LLM 跑偏"这类真正影响团队采纳决策的问题。

延伸阅读（仓库内路径）

• docs/concepts/sdd.md：本文主体，SDD 概念定义
• spec-driven.md：SDD 完整方法论深潜
• docs/quickstart.md：端到端实操（Taskify 示例）
• docs/reference/agentic-sdd.md：每条命令的详细参考
• docs/concepts/spec-persistence.md：规范持久化模型
• docs/guides/evolving-specs.md、docs/guides/existing-projects.md：棕地演化与存量项目采纳
• templates/spec-template.md、templates/plan-template.md、templates/constitution-template.md：核心模板
• workflows/speckit/workflow.yml：内置 SDD 全流程工作流