layout: post keywords: SDD description: 对SDD的理解以及在生产环境下落地的思考 title: 规范驱动开发(SDD)在生产环境下的落地实践 categories: [测试] tags: [SDD] group: archive icon: google —

规范驱动开发(SDD)在生产环境下的落地实践

文档版本: v1.1
编写日期: 2026年1月
适用对象: 软件开发工程师、技术负责人、架构师

摘要

随着生成式AI在软件开发领域的深度渗透，传统的”提示-生成-修补”式开发模式（业界称为Vibe Coding）在生产级项目中暴露出严重的可维护性和一致性问题。规范驱动开发（Specification-Driven Development, SDD）作为一种将规范置于工程核心的方法论，正在成为AI辅助开发从”玩具”走向”生产级工具”的关键路径。本文系统阐述SDD的核心概念、产生背景、解决方案，并基于实际工程落地经验，深入分析当前主流工具的适用场景与局限性，最后提出面向生产环境的改进思路。

关键词: 规范驱动开发; SDD; AI辅助编程; spec-kit; 上下文工程; 生产级软件

1. 引言

软件工程正处于一个关键的转折点。

2024年以来，以GitHub Copilot、Claude Code、Cursor为代表的AI编程助手已深刻改变了开发者编写代码的方式。然而，当这些工具从个人项目、快速原型走向企业级生产系统时，一个根本性问题逐渐浮出水面：AI擅长生成代码片段，但缺乏对项目整体架构、业务上下文和技术约束的深度理解。

这种局限性在小型项目中尚可接受，但在涉及数十万行代码、多团队协作、复杂业务逻辑的生产环境中，会导致代码风格不一致、架构设计偏离、技术债务快速累积等严重问题。

规范驱动开发（SDD）正是在这一背景下应运而生。它不是对AI能力的否定，而是对AI使用方式的系统性升级——通过将规范（而非代码）置于开发流程的核心，为AI提供充分的上下文和明确的约束，从而实现可控、可预测、可维护的AI辅助开发。

本文旨在为软件开发人员提供一份关于SDD的系统性认知材料，帮助读者理解其核心理念、评估其适用场景，并为生产环境落地提供实践参考。

2. 什么是规范驱动开发(SDD)

2.1 定义

规范驱动开发（Specification-Driven Development, SDD）是一种将规范（而非代码）视为软件开发主要产物的方法论。在SDD范式下，代码被视为严格定义的规范的”最后一公里”实现，是规范在特定技术栈中的具体表达。

核心命题: 规范是新的源代码。代码是规范的编译产物。

这一理念与传统软件工程中”文档先行”的思想有本质区别。传统的需求文档和设计文档往往是一次性产物，在开发过程中逐渐与实际代码脱节。而SDD中的规范是活文档（Living Document），它贯穿整个开发生命周期，是人类开发者与AI代理共享的唯一真实来源（Single Source of Truth）。

2.2 核心原则

SDD建立在以下四个基础原则之上：

原则一：规范作为通用语言

规范成为项目沟通的通用语言，代码只是该语言在选定框架中的具体表达。软件维护从”修改代码”转变为”迭代规范”。这意味着当需求变更时，首先更新规范，然后由AI（或人工）重新生成相应代码。

原则二：可执行规范

为了弥合意图与实现之间的差距，规范必须精确、完整且无歧义——足以让AI代理在最小人类干预下生成可工作的系统。这要求规范不仅描述”做什么”，还要明确”为什么”以及关键的”如何”约束。

原则三：上下文工程作为基石

SDD的核心功能是为AI代理提供稳健、持久的上下文。无论是constitution.md（项目宪章）、spec.md（功能规范）还是plan.md（技术计划），这些产物都是上下文工程的输出。它们为AI行为设置明确的护栏，将输出与项目目标、架构约束和编码标准对齐。

原则四：开发者角色转型

人类开发者从代码生产者转变为架构师、AI向导和输出验证者。开发者的核心工作变成在规范阶段定义”什么”和”为什么”，在计划阶段定义高层次”如何”，将语法和实现细节留给AI处理。

2.3 SDD成熟度模型

参考Martin Fowler的分析框架，SDD的采用可分为三个成熟度级别：

级别	名称	特征	典型实践
Level 1	规范优先	为特定任务编写规范，开发完成后可能丢弃	单次AI辅助开发任务
Level 2	规范锚定	规范是活文档，在功能生命周期中持续维护	大多数SDD工具的目标级别
Level 3	规范即源	规范是人类编辑的唯一产物，代码完全由AI生成	未来愿景，当前尚未完全实现

当前大多数SDD工具和实践处于Level 1到Level 2之间的过渡阶段。

3. SDD产生的背景

3.1 Vibe Coding的兴起与局限

2023-2024年间，随着AI编程工具的普及，一种被称为”Vibe Coding”（氛围编程）的开发模式迅速流行。其典型特征是：

即兴式交互: 开发者通过自然语言提示与AI对话，快速获取代码片段
提示-粘贴-祈祷: 将AI生成的代码直接粘贴到项目中，期望其能正常工作
迭代式修补: 遇到问题时，通过追加提示让AI修复

这种模式在以下场景中表现出色：

快速原型验证
学习新技术栈
编写独立的工具脚本
个人项目开发

然而，当项目规模扩大、复杂度提升时，Vibe Coding的问题开始显现：

项目初期（2周内）：
  ✓ 快速推进，功能快速实现
  ✓ 感觉像发现了"编码作弊码"

项目中期（1-2月）：
  ✗ AI开始犯"昂贵的错误"
  ✗ 错误地重写整个文件
  ✗ 创建已存在的函数
  ✗ 添加新功能时破坏现有功能

项目后期：
  ✗ 代码库像"没人相互交流的小组项目"
  ✗ 不一致的状态管理、样式、API模式
  ✗ 技术债务快速累积

3.2 AI编程工具的根本性局限

Vibe Coding失效的根本原因在于当前AI编程工具的几个核心局限：

局限一：上下文窗口的物理限制

即使是最先进的大语言模型，其上下文窗口也存在物理限制（通常为128K-200K tokens）。对于大型代码库，AI无法同时”看到”所有相关代码，导致生成的代码与现有架构不一致。

局限二：缺乏项目级语义理解

传统AI编程工具主要基于当前编辑器中有限上下文的文本分析来生成建议。它们缺乏对项目整体结构的理解，在涉及复杂类型系统、跨文件引用、项目特定配置时，建议往往不够精准。

局限三：无状态性导致的上下文丢失

LLM本质上是无状态的。每次对话都是独立的，之前建立的项目理解、架构决策、编码约定都需要重新注入。这导致：

重复解释相同的项目背景
AI”遗忘”之前的设计决策
输出风格和模式不一致

局限四：幻觉问题

AI可能生成语法正确但逻辑或语义上错误的代码——即”幻觉”（Hallucination）。在缺乏充分上下文约束的情况下，这种问题尤为严重。

3.3 从”代码是真相”到”意图是真相”

SDD的出现标志着软件开发范式的根本转变：

维度	传统模式	SDD模式
真相来源	代码	规范
人类核心工作	编写代码	定义意图和约束
AI角色	代码补全助手	规范执行者
维护方式	修改代码	迭代规范
质量保障	代码审查	规范审查 + 输出验证

这一转变的驱动力是：AI使规范变得可执行。当规范能够自动转化为可工作的代码时，规范本身就决定了构建什么。

4. SDD解决的核心问题

4.1 问题域概览

SDD旨在解决AI辅助开发中的以下核心问题：

┌─────────────────────────────────────────────────────────────┐
│                    SDD解决的问题域                           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 上下文丢失  │  │ 输出不一致  │  │ 架构偏离    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ 意图模糊    │  │ 知识孤岛    │  │ 可追溯性差  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

4.2 具体问题分析

问题一：上下文丢失与重复注入

在Vibe Coding模式下，开发者需要在每次AI交互中重复提供项目背景、架构约束、编码规范等信息。这不仅效率低下，还容易遗漏关键信息，导致AI输出偏离预期。

问题二：输出一致性难以保障

缺乏统一的规范约束，AI在不同时间、不同上下文下生成的代码可能采用完全不同的模式、风格和架构决策。这导致代码库逐渐变成”拼凑的怪物”。

问题三：架构设计与实现脱节

AI倾向于生成”通用解决方案”，而非与现有架构深度集成的代码。特别是在棕地项目（Brownfield Project）中，AI生成的代码往往与存量代码的架构风格不匹配。

问题四：意图传递的模糊性

自然语言提示本身具有模糊性。”为我的应用添加照片分享功能”这样的提示，迫使AI猜测成千上万个未声明的需求——存储方式、权限控制、UI风格、性能要求等。

问题五：团队知识的孤岛化

在传统开发中，关于安全策略、合规规则、设计系统约束、集成需求等知识往往存在于：

某人的脑海中
被埋没在无人阅读的Wiki中
散布在无法检索的Slack对话中

AI无法访问这些隐性知识，导致生成的代码违反团队约定。

问题六：变更的可追溯性

当需求变更时，如何追溯变更对设计、代码、测试的影响？Vibe Coding模式下，这种追溯几乎不可能实现。

5. SDD的解决方案与方法

5.1 核心解决思路

SDD的核心解决思路可以概括为：将AI视为一个有能力但缺乏经验的队友——技术熟练但需要适当方向和上下文的人。

这意味着：

不是给AI更多的自由度，而是给它更明确的约束
不是期望AI理解一切，而是主动提供它需要的信息
不是让AI做决策，而是让AI执行已经做好的决策

5.2 结构化工作流

以GitHub spec-kit为代表的SDD工具，通常采用四阶段门控工作流：

┌──────────────────────────────────────────────────────────────┐
│                    SDD四阶段工作流                            │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐  │
│   │ Specify │ -> │  Plan   │ -> │  Tasks  │ -> │Implement│  │
│   │  规范   │    │  计划   │    │  任务   │    │  实现   │  │
│   └─────────┘    └─────────┘    └─────────┘    └─────────┘  │
│       │              │              │              │         │
│       v              v              v              v         │
│   定义什么      技术约束       可执行单元      代码生成      │
│   和为什么      和架构         和验收标准      和验证        │
│                                                              │
└──────────────────────────────────────────────────────────────┘

阶段一：Specify（规范）

使用/spec命令创建功能规范，高层次定义”什么”和”为什么”。规范应包括：

问题的清晰描述
功能需求与非功能需求
用户故事或用例
约束和限制
成功标准

阶段二：Plan（计划）

使用/plan命令生成技术实施计划，定义”如何”实现。计划应包括：

技术栈选择
架构设计决策
与现有系统的集成点
数据模型设计
API设计

阶段三：Tasks（任务）

使用/tasks命令将计划分解为小的、可审查的、可测试的执行单元。每个任务应该：

足够小，可以独立完成和验证
有明确的验收标准
与其他任务的依赖关系清晰

阶段四：Implement（实现）

AI代理按照任务列表逐一实现，生成代码并进行验证。

5.3 上下文工程实践

上下文工程是SDD的核心技术支撑。其目标是构建一套机制，使AI在每次交互中都能获得充分、准确、相关的项目上下文。

实践一：项目宪章（Constitution）

创建constitution.md或类似文件，以AI可读的格式编纂项目的核心约束：

技术栈和版本要求
编码规范和风格指南
架构原则和设计模式
安全和合规要求
测试策略

实践二：活文档体系

建立一套随项目演进而持续更新的文档体系：

project/
├── .spec/
│   ├── constitution.md      # 项目宪章
│   ├── architecture.md      # 架构设计
│   ├── features/
│   │   ├── feature-001/
│   │   │   ├── spec.md      # 功能规范
│   │   │   ├── plan.md      # 技术计划
│   │   │   └── tasks.md     # 任务列表
│   │   └── ...
│   └── knowledge/
│       ├── api-patterns.md  # API模式
│       └── testing.md       # 测试约定

实践三：增量上下文注入

根据当前任务的需要，选择性地将相关上下文注入AI提示。避免一次性注入过多信息导致上下文窗口溢出或信息稀释。

5.4 上下文工程的理论基础

有效的上下文工程需要建立在对大语言模型工作机制的深刻理解之上。基于Anthropic等机构的研究成果，上下文管理面临两个核心挑战：

挑战一：上下文腐蚀（Context Rot）

研究表明，随着上下文窗口中token数量的增加，模型准确回忆和利用信息的能力会呈现梯度下降。这种下降并非断崖式的，而是渐进的——信息检索精度和长程推理能力持续降低。

上下文腐蚀会导致恶性循环：

加载更多信息 → 窗口膨胀 → 信息检索精度下降 → AI行为异常
       ↓
人工发现问题 → 追加更多上下文纠正 → 窗口进一步膨胀 → 问题加剧

挑战二：注意力预算耗尽（Attention Budget Exhaustion）

Transformer架构的固有约束决定了LLM存在”注意力预算”：

每个token都需要与所有其他token建立注意力关系，产生n²级别的计算开销
训练数据中短序列远多于长序列，模型对长上下文依赖的学习经验相对不足
位置编码的插值处理虽然允许更长序列，但会降低token位置理解的精度

这意味着：

每引入一个新token都会消耗注意力预算
低质量token会”稀释”高质量信息的影响力
关键信息可能被噪声淹没

核心指导原则

找到最小可能的高信号token集合，最大化期望结果的可能性。

基于上述理论，有效的上下文工程应遵循以下策略：

策略	传统方式	推荐方式
信息加载	预加载所有可能相关的文档	即时加载（Just-in-Time），按阶段动态加载
信息组织	扁平化存储	分层组织（概要层→技术层→经验层→详细层）
长任务处理	单一上下文持续累积	上下文压缩 + 结构化笔记系统
工具设计	功能丰富的复合工具	边界清晰的单一职责工具

5.5 为什么这种方法有效

SDD之所以能够成功，而”简单提示AI”会失败，源于对大语言模型工作原理的深刻理解：

LLM在模式补全方面非常出色，但在心灵感应方面并不擅长。

模糊的提示迫使模型猜测未声明的需求，AI会做出”合理的假设”，而其中一些假设必然是错误的——而且往往直到深入实现时才会发现问题。

相比之下，预先提供清晰的规范、技术计划和专注的任务，给予AI更多的清晰度：

它不再猜测你的需求，而是知道要构建什么
它不再即兴发挥架构，而是遵循既定设计
它不再随机选择模式，而是匹配现有风格

6. 主流SDD工具对比分析

6.1 工具概览

当前SDD领域有四个具有代表性的开源项目，各自体现了不同的设计哲学：

工具	核心理念	GitHub Stars	主要特点
BMAD-METHOD	代理敏捷团队	19.1k ⭐	模拟人类敏捷团队的AI角色分工
spec-kit	企业级结构化工作流	39.3k ⭐	GitHub官方支持，代理无关
OpenSpec	棕地确定性	2.1k ⭐	专注现有代码库的增量开发
PromptX	自然语言上下文	1.5k ⭐	简化AI交互，提示词管理

6.2 详细对比

6.2.1 BMAD-METHOD

设计哲学: 代理敏捷驱动开发（Agentic Agile-Driven Development）

BMAD模拟具有专门AI角色的人类敏捷团队，以对抗”规划不一致”和”上下文丢失”问题。

工作流程:

代理规划阶段: 分析师、PM和架构师代理与用户协作，制作详细的PRD和架构文档
上下文工程化开发: Scrum-Master代理将规划文档转换为超详细的开发故事

技术实现: Node.js v20+, JavaScript

适用场景:

复杂项目，需要多角色协作
企业级敏捷流程
希望模拟完整开发团队的场景

局限性:

学习曲线较陡
对于简单项目可能过于复杂
角色切换带来的上下文管理开销

6.2.2 GitHub spec-kit

设计哲学: 将AI辅助开发标准化为结构化的、可重复的、可验证的工作流

工作流程: 严格的四阶段门控流程（Specify → Plan → Tasks → Implement）

技术实现: CLI工具（specify命令），使用模板和脚本搭建项目

核心优势:

代理无关: 支持Copilot、Claude、Gemini等多种AI代理
企业友好: GitHub官方支持，与GitHub生态系统深度集成
标准化: 提供统一的工作流模板

适用场景:

企业需要标准化AI开发流程
多AI代理混合使用的环境
与GitHub工作流深度集成的项目

6.2.3 OpenSpec

设计哲学: 在保持轻量级的同时为AI开发带来确定性和可审计性

核心差异化: 棕地优先——认识到大多数开发发生在现有代码库中，而非绿地项目

工作流程:

快照与差异分析: 创建代码库快照，记录所有变更，支持增量审查
结构化规范: 以YAML/JSON格式定义功能需求
可审查的AI输出: AI生成变更提议，供人类审查和合并
测试生成: 从规范自动生成单元和集成测试

技术实现: TypeScript, CLI工具

适用场景:

现有代码库的功能增强
需要确定性和可审计性的场景
增量开发，而非全新构建

6.2.4 PromptX

设计哲学: AI的自然语言上下文管理平台

工作流程:

提示词管理: 存储、版本化和组织提示词模板
上下文注入: 将相关上下文注入AI对话
多Agent协调: 协调多个AI代理协作完成任务
插件系统: 扩展平台功能

适用场景:

简化AI交互体验
提示词资产管理
多代理协调场景

6.3 选型决策框架

                    ┌─────────────────────────────┐
                    │      项目类型判断           │
                    └─────────────────────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
              v                  v                  v
        ┌──────────┐      ┌──────────┐      ┌──────────┐
        │ 绿地项目 │      │ 棕地项目 │      │ 混合场景 │
        └──────────┘      └──────────┘      └──────────┘
              │                  │                  │
              v                  v                  v
        ┌──────────┐      ┌──────────┐      ┌──────────┐
        │ spec-kit │      │ OpenSpec │      │   BMAD   │
        │   BMAD   │      │          │      │ spec-kit │
        └──────────┘      └──────────┘      └──────────┘

选型建议:

场景	推荐工具	理由
企业标准化流程	spec-kit	GitHub官方支持，代理无关，易于推广
复杂项目多角色协作	BMAD	完整的角色分工，适合大型团队
现有代码库改造	OpenSpec	棕地优先设计，增量开发友好
快速上手，简化交互	PromptX	学习曲线平缓，注重用户体验

7. 生产级工程落地中的问题

基于实际工程落地经验，SDD在生产环境中面临以下典型问题：

7.1 架构理解与一致性问题

问题表现:

生成的代码架构与存量代码不匹配，偏差较大
AI倾向于生成新模块或新建架构，而非融入现有体系
缺乏架构设计和架构澄清环节

典型案例:

以Shell为主的备份系统，AI输出的都是新设计的Python代码，完全忽略了现有的技术栈约束。

根因分析:

SDD流程对代码架构考虑不足
Specify阶段过于强调意图，对架构约束描述不够
缺乏对存量代码架构的系统性分析机制

7.2 流程步骤间的一致性问题

问题表现:

Plan和需求澄清存在差异
Spec中的设计在Plan中被遗漏或变更
Task生成具有随机性，多次执行结果不一致

典型案例:

Spec中明确”基于缓存的情况来进行持久化”，但在Plan中直接进行了持久化设计，遗漏了缓存环节。

根因分析:

各阶段之间缺乏强制的一致性校验
LLM的随机性导致输出不稳定
变更点没有在流程中显式追踪

7.3 上下文窗口与知识注入问题

问题表现:

大模型上下文窗口限制，很多隐性知识无法输入
代码库的隐性知识（历史因素导致的定制结构、非代码可识别的业务逻辑）难以传递
知识库需要支持，但没有统一的获取方式

典型案例:

代码库中同时存在相同功能的不同实现（历史原因），AI无法识别应该使用哪个版本。

根因分析:

隐性知识难以结构化表达
缺乏知识库与SDD流程的集成机制
上下文压缩策略可能丢失关键信息

7.4 代码细节调整的闭环问题

问题表现:

SDD流程执行完成后，实现细节需要调整时，无法基于原有输出完成修正
代码完成后发现问题，需要同时调整前面的设计文档
缺乏从实现反馈到规范的逆向更新机制

根因分析:

SDD输出不会到实现细节的程度
流程是单向的，缺乏反馈闭环
文档与代码的同步更新机制缺失

7.5 相似需求参考能力缺失

问题表现:

已开发过类似需求，但SDD无法参考之前的实现
每次都从头开始，没有复用机制
参考范围应包括：设计阶段、代码增量、测试用例

根因分析:

SDD过程记录采用编号形式（如001），不方便追溯到类似需求
缺乏需求相似度匹配和历史参考机制
知识沉淀与复用体系未建立

7.6 多代码库场景的定位问题

问题表现:

一个需求涉及多个代码库时，代码生成位置不正确
需要反复提醒AI正确的代码库位置
多个库放在一起容易混淆，拆分开又增加管理复杂度

根因分析:

缺乏多代码库的统一视图和定位机制
代码库边界和职责划分信息未充分传递给AI

7.7 测试生成质量问题

问题表现:

单元测试不符合存量测试架构
E2E测试用例存在冗余
测试场景冗余导致后续代码生成也产生冗余

根因分析:

测试架构信息未纳入上下文
缺乏测试用例去重和优化机制
测试策略与实现策略脱节

7.8 问题汇总表

问题类别	具体问题	影响程度	改进方向
架构一致性	生成代码与存量架构不匹配	高	增强架构分析和澄清环节
流程一致性	步骤间内容不一致	中	增加一致性校验机制
上下文管理	隐性知识难以注入	高	建设知识库集成机制
闭环反馈	无法从实现反馈到规范	中	增加analyze命令
知识复用	无法参考相似需求	中	建立需求相似度匹配
多库管理	代码生成位置不准确	中	增强代码库定位信息
测试质量	测试不符合存量架构	中	纳入测试架构上下文

7.9 根本性问题：边际成本恒定

上述问题的共同根因可以归结为一点：当前SDD工具缺乏知识复利机制。

在理想状态下，重复执行同类需求的边际成本应当递减：

执行次数	理想状态	当前现实
第1次执行某类需求	45分钟（建立基础）	45分钟
第2次执行同类需求	15分钟（复用经验）	45分钟（重新回忆遗漏点）
第N次执行同类需求	5分钟（高度自动化）	45分钟（边际成本恒定）

问题本质分析：

执行过程中的知识未被系统性记录：实施阶段发现的问题、排查路径、解决方案等信息在流程结束后丢失
知识停留在人脑而非工具链：每次执行都依赖人工回忆历史经验，而非系统自动加载
缺乏从实践到规范的反馈机制：SDD流程是单向的（规范→代码），缺少逆向更新路径

这意味着SDD工具解决了”规范化”问题，但尚未解决”知识复用”问题。边际成本恒定是制约SDD在生产环境中发挥更大价值的关键瓶颈。

7.10 Spec详细程度的悖论

规范驱动开发存在一个内在的方法论矛盾：

Spec越详细 → 越接近代码本身 → 需要同时维护Spec和Code两套产物
Spec越简略 → 越难精确指导AI → 失去规范的意义

详细Spec的问题：

当Spec详细到可以精确指导AI生成代码时，它本身就变成了另一种形式的”代码”：

需要同时维护Spec和Code两套产物，且必须保持同步
代码变更需要同步更新Spec，Spec变更需要重新生成代码
实际维护成本可能翻倍

简略Spec的问题：

当Spec过于简略时，AI缺乏足够的约束信息：

生成结果的随机性增加
与现有架构的一致性难以保障
规范的指导价值降低

可能的解决方向：

采用”分层概要 + 代码指针”策略，而非追求详尽的Spec：

推荐的上下文组织方式：
├── 服务概要：服务职责、边界定义
├── 业务概要：核心业务流程、关键概念
├── 模块概要：模块职责、依赖关系
├── 接口概要：对外接口、调用方式
└── 代码指针：具体细节参见 xxx/xxx.go 的 xxx 函数

不推荐维护：
├── ❌ 详细的数据结构定义（代码中已有）
├── ❌ 完整的接口参数说明（代码中已有）
├── ❌ 具体的实现逻辑描述（代码中已有）
└── ❌ 任何可以从代码直接获取的信息

核心原则：概要层帮助AI快速定位，细节层直接读取代码。避免维护一份”像代码一样详细的Spec文档”——那只是换了格式的代码，并未降低复杂度，反而增加了同步成本。

8. 解决方案的思考与展望

8.1 短期改进方向

针对当前落地问题，以下改进措施可在短期内实施：

改进一：增强架构澄清环节

在现有流程中增加架构分析和澄清步骤：

原流程: Spec → Clarify → Plan → Tasks → Implement

改进流程: Spec → Clarify Spec → Research → Clarify Arch & Detail → Plan → Tasks → Implement

Research阶段: 增加对存量架构和测试架构的理解
Clarify Arch: 明确架构约束和集成点

改进二：增加一致性校验机制

每个步骤完成后，执行变更点核对
建立变更追踪清单，确保关键信息在流程中传递
引入analyze命令，用于检测和纠正文档不一致

改进三：完善项目宪章内容

在Constitution中补充：

测试架构和测试策略
代码库边界和职责划分
存量代码的关键模式和约定
已知的技术债务和历史遗留问题

改进四：建立反馈闭环

开发debug命令，用于：

测试问题反馈和闭环
MVP问题的修正
从实现反馈到规范的逆向更新

8.2 中期建设方向

方向一：知识库体系建设

建立与SDD流程集成的知识库：

公共知识库：通用的架构模式、最佳实践
项目知识库：项目特定的约定、历史决策
需求知识库：历史需求与实现的映射

方向二：需求分类与适用性指引

不同类型的需求，SDD效果差异显著。建立需求分类指引：

需求类型	SDD适用性	关键判断维度	建议做法
功能增强（棕地）	高	边界清晰、有历史参考	标准SDD流程
全新功能（绿地）	高	架构约束明确	先架构设计，再SDD
性能优化	中	需要实验验证	先Vibe Coding穿刺，明确方案后再SDD
技术重构	中	影响范围大	需要充分的架构分析和风险评估
问题修复	低	紧急、范围小	直接Vibe Coding可能更高效
跨服务需求	中-低	协作复杂度高	SDD管理规范，但实现需要更多人工协调

方向三：LSP集成增强语义理解

借鉴Claude Code原生集成LSP的思路，增强AI对代码库的语义理解：

通过LSP获取类型定义、符号引用、代码结构
实现基于语义的代码导航和理解
提供更精准的代码补全和重构建议

方向四：多Agent协作架构

针对上下文窗口爆满问题，业界正在探索Subagent架构作为解决方案：

传统模式（单一Agent）：

用户输入 → 单一Agent处理所有任务 → 上下文持续膨胀 → 窗口爆满 → 任务失败

Subagent模式：

用户输入 → 主Agent（决策层）
              ↓
    意图识别 + 任务拆分
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
Subagent1  Subagent2  Subagent3
(独立窗口)  (独立窗口)  (独立窗口)
    └─────────┼─────────┘
              ↓
    结果汇总 → 主Agent继续

Subagent架构的核心优势：

维度	单一Agent模式	Subagent模式
上下文管理	持续累积，易爆满	独立窗口，按需加载
任务复杂度	受限于单一窗口容量	可处理更复杂的长任务
状态传递	依赖上下文记忆	通过结构化文件传递
失败恢复	需要从头开始	可从断点继续

状态传递机制：

Subagent之间不共享上下文窗口，通过结构化状态文件保证信息传递：

每个Subagent启动时读取状态文件，快速理解当前状态
执行过程中专注自身任务，不受其他任务干扰
结束时更新状态文件，完成”干净的交接”

核心原则：每个Subagent只完成一个”原子任务”。这类似于人类团队的轮班协作模式——不是一个工程师连续工作48小时，而是多个工程师各工作4小时但交接清晰。

这一方向与BMAD-METHOD的多角色设计理念一致，但更强调上下文隔离和状态传递机制。

8.3 长期演进愿景

愿景一：规范层的统一

建立代码之上的统一”规范层”：

SDD创建功能/技术规范
AI-BDD消费规范生成行为规范（Gherkin）
AI契约工具消费规范生成API规范（契约）
AI充当层之间的编译器

愿景二：左移到极致

重新定义”左移”：测试发生在编码之前

QA从”在代码中找bug”转变为”在规范中发现歧义”
规范审查成为质量保障的第一道防线
代码生成后的验证变成确认性测试

愿景三：自主代理团队

参考MetaGPT的哲学：”代码=SOP(团队)”

实例化LLM代理虚拟团队（PM、架构师、工程师、QA）
从单个高层需求自主交付整个项目
人类角色进一步向”规范定义者”和”输出验证者”转移

与人类团队的类比：

人类团队：
├── 产品经理：理解需求、拆解任务
├── 技术负责人：设计方案、分配工作
├── 开发工程师：实现功能
├── 测试工程师：验证质量
└── 通过会议和文档进行协调

Agent团队：
├── 需求分析Agent：理解意图、路由任务
├── 架构设计Agent：设计方案
├── 实现执行Agent：生成代码
├── 测试验证Agent：验证质量
└── 通过结构化状态文件进行协调

当前范式：AI执行一步，人工检查，批准后继续。

未来范式：人设定目标，Agent团队自主协作数小时甚至数天，人验收最终结果。人的角色从”操作者”转变为”监督者”，从”指令发出者”转变为”目标设定者”。

8.4 对技术团队的建议

基于以上分析，对正在或计划采用SDD的技术团队提出以下建议：

建议一：投资培训，转变技能重心

从语言特定技能转向更高阶能力：

需求工程：如何精确表达意图
系统设计：如何定义架构约束
上下文工程：如何为AI提供有效信息
输出评估：如何验证AI生成的代码

建议二：从棕地项目开始验证

通过OpenSpec等工具在现有项目上引入SDD，进行低风险、高价值的验证：

选择边界清晰的功能模块
积累经验后再推广到更复杂场景
记录问题和改进点，持续优化流程

建议三：建立项目宪章

今天就创建constitution.md，以AI可读的格式编纂：

技术栈和版本约束
编码规范和设计模式
架构原则和边界
测试策略和质量标准

建议四：提升规范质量意识

在文化上将规范质量提升到与代码质量同等水平：

规范审查与代码审查同等重要
庆祝清晰、无歧义的规范作为核心工程工艺
建立规范编写的最佳实践和模板

建议五：建立知识沉淀机制

针对边际成本恒定问题，建立系统化的知识沉淀机制：

在流程关键节点自动触发经验记录
将排查路径、解决方案结构化存储
建立经验检索机制，在相似场景自动加载历史知识

9. 结语

规范驱动开发（SDD）不是对AI编程能力的否定，而是对其使用方式的系统性升级。它代表了软件工程在AI时代的一次重要范式转变：从”代码是真相”到”意图是真相”，从”人写代码”到”人定义规范、AI生成代码”。

这一转变的核心洞察是：AI擅长执行，但需要人类提供方向。通过将规范置于开发流程的核心，SDD为AI提供了充分的上下文和明确的约束，使其从”聪明但不可靠的助手”升级为”可控且可预测的执行者”。

然而，SDD并非银弹。在生产环境落地过程中，我们面临架构理解不足、流程一致性难以保障、隐性知识难以传递、边际成本恒定等现实挑战。特别是Spec详细程度的悖论——过于详细则变成另一种形式的代码，过于简略则失去指导价值——揭示了SDD方法论本身的内在张力。

这些问题的解决需要工具层面的持续改进：上下文工程的深化、多Agent协作架构的探索、知识复利机制的建立。更需要团队在实践中不断积累经验、优化流程，找到适合自身场景的平衡点。

展望未来，随着AI能力的持续提升和SDD工具链的不断成熟，我们有理由相信：掌握规范编写能力的工程师，将在AI时代拥有更大的竞争优势。因为在这个新范式下，最有价值的不是编写最聪明代码的人，而是编写最清晰规范的人。

软件工程的未来不是打字更快，而是思考更清晰。

10. 参考文献

[1] Li Shen. “Spec-Driven Development (SDD) Is the Future of Software Engineering”. Medium, 2025.

[2] Den Delimarsky. “Spec-driven development with AI: Get started with a new open source toolkit”. GitHub Blog, 2025.

[3] Martin Fowler. “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”. martinfowler.com, 2025.

[4] GitHub. “spec-kit: Toolkit to help you get started with Spec-Driven Development”. github.com/github/spec-kit, 2025.

[5] BMAD Code Organization. “BMAD-METHOD: Breakthrough Method for Agentic Development”. github.com/bmad-code-org/BMAD-METHOD, 2025.

[6] Fission AI. “OpenSpec: Spec-driven development for AI”. github.com/Fission-AI/OpenSpec, 2025.

[7] Deepractice. “PromptX: Leading AI agent context platform”. github.com/Deepractice/PromptX, 2025.

[8] Anthropic. “Claude Code Native LSP Support”. Claude Code Changelog, 2025.

[9] Visual Studio Magazine. “GitHub Open Sources Kit for Spec-Driven AI Development”. 2025.

[10] DEV Community. “Spec Driven Development (SDD) - A initial review”. dev.to, 2025.

[11] Anthropic. “Effective Context Engineering for AI Agents”. Anthropic Research, 2025.

附录A：术语表

术语	英文	定义
规范驱动开发	Specification-Driven Development (SDD)	将规范置于开发流程核心的方法论
氛围编程	Vibe Coding	即兴式、提示-粘贴-祈祷式的AI辅助开发方式
上下文工程	Context Engineering	为AI提供充分、准确、相关项目上下文的技术实践
上下文腐蚀	Context Rot	随着上下文窗口token增加，模型信息回忆能力下降的现象
注意力预算	Attention Budget	LLM处理信息时的注意力资源限制
项目宪章	Constitution	编纂项目核心约束的AI可读文档
活文档	Living Document	随项目演进持续更新的文档
棕地项目	Brownfield Project	在现有代码库基础上进行的开发
绿地项目	Greenfield Project	从零开始的全新项目开发
幻觉	Hallucination	AI生成语法正确但逻辑错误的输出
边际成本	Marginal Cost	每增加一个单位产出所需的额外成本
Subagent	Subagent	在多Agent架构中负责特定子任务的独立Agent

附录B：可扩展内容与图片建议清单

以下内容可根据需要进一步扩展，并建议配合相应图片增强可读性：

B.1 建议补充的图片

位置	图片主题	建议来源/绘制方式
2.2节	SDD核心原则示意图	自绘四象限图或流程图
3.2节	Vibe Coding vs SDD对比图	参考GitHub官方博客配图风格
5.3节	上下文工程架构图	参考BMAD-METHOD架构图
5.4节	上下文腐蚀示意图	展示token增加与精度下降的关系曲线
6.3节	四种工具定位象限图	自绘，X轴轻量-重量，Y轴绿地-棕地
7节	生产落地问题分类图	鱼骨图或问题树
7.9节	边际成本对比图	展示理想状态与当前现实的成本曲线
8.2节	多Agent协作架构图	展示主Agent与Subagent的协作关系
8.3节	SDD演进路线图	时间轴或阶段图

B.2 可扩展的内容方向

方向一：具体工具的详细使用指南

spec-kit的安装配置和命令详解
BMAD-METHOD的角色定义和工作流配置
OpenSpec的快照机制和差异分析

方向二：案例研究

成功落地SDD的项目案例
从Vibe Coding迁移到SDD的转型经验
不同规模团队的SDD实践差异

方向三：与其他方法论的结合

SDD与敏捷开发的结合
SDD与DevOps流程的集成
SDD与测试驱动开发(TDD)的关系

方向四：度量与评估

SDD效果的量化评估指标
规范质量的评估标准
AI生成代码质量的度量方法

方向五：组织变革

引入SDD的组织变革管理
团队技能转型路径
文化和流程的配套调整

方向六：上下文工程深化

分层上下文组织的最佳实践
即时加载策略的实现方案
上下文压缩与笔记系统的设计

方向七：知识复利机制

经验沉淀的触发时机与格式设计
经验检索的匹配算法
从文档到Skill到Command的演进路径

B.3 推荐的外部资源链接

GitHub spec-kit官方仓库: https://github.com/github/spec-kit
BMAD-METHOD官方仓库: https://github.com/bmad-code-org/BMAD-METHOD
OpenSpec官方仓库: https://github.com/Fission-AI/OpenSpec
Martin Fowler的SDD分析文章: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
GitHub官方博客SDD介绍: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
Anthropic上下文工程指南: https://www.anthropic.com/research/context-engineering

文档结束

本文档基于2026年1月的技术现状编写，SDD领域发展迅速，建议定期关注相关工具和方法论的更新。

Sdd在生产环境应用

规范驱动开发(SDD)在生产环境下的落地实践

摘要

目录

1. 引言

2. 什么是规范驱动开发(SDD)

2.1 定义

2.2 核心原则

2.3 SDD成熟度模型

3. SDD产生的背景

3.1 Vibe Coding的兴起与局限

3.2 AI编程工具的根本性局限

3.3 从”代码是真相”到”意图是真相”

4. SDD解决的核心问题

4.1 问题域概览

4.2 具体问题分析

5. SDD的解决方案与方法

5.1 核心解决思路

5.2 结构化工作流

5.3 上下文工程实践

5.4 上下文工程的理论基础

5.5 为什么这种方法有效

6. 主流SDD工具对比分析

6.1 工具概览

6.2 详细对比

6.2.1 BMAD-METHOD

6.2.2 GitHub spec-kit

6.2.3 OpenSpec

6.2.4 PromptX

6.3 选型决策框架

7. 生产级工程落地中的问题

7.1 架构理解与一致性问题

7.2 流程步骤间的一致性问题

7.3 上下文窗口与知识注入问题

7.4 代码细节调整的闭环问题

7.5 相似需求参考能力缺失

7.6 多代码库场景的定位问题

7.7 测试生成质量问题

7.8 问题汇总表

7.9 根本性问题：边际成本恒定

7.10 Spec详细程度的悖论

8. 解决方案的思考与展望

8.1 短期改进方向

8.2 中期建设方向

8.3 长期演进愿景

8.4 对技术团队的建议

9. 结语

10. 参考文献

附录A：术语表

附录B：可扩展内容与图片建议清单

B.1 建议补充的图片

B.2 可扩展的内容方向

B.3 推荐的外部资源链接