AI开发新范式——规范驱动开发（SDD）：通过OpenSpec实现增量开发【SDD第三讲】

程序绝大部分都是在已有软件上进行新增功能的开发，那么，在SDD编程中，如何管理增量开发中的规范变更？OpenSpec框架给出了答案。

引言：AI编程的痛点

当软件开发进入AI时代，从氛围编程到SDD(规范驱动开发)，在AI研发范式的探索上越来越深入。SPEC KIT给SDD一个规范的框架，但是，我们看到SPEC KIT主要解决全新开发的模式，而在一个软件的研发过程中，基于存量系统进行增量开发才是软件开发的常态。那么，在已有系统基础上添加新功能时，如何让AI Agent快速理解项目现状，并按照既定规范进行开发？开源框架OpenSPEC给出了适当的探索。

回顾 SDD：规范即真理

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

规范驱动开发（Spec-Driven Development, SDD）是一种软件开发方法论，其核心理念是：

SDD vs 传统开发

传统开发流程：

需求文档 → 设计文档 → 代码实现 → 测试文档
     ↓         ↓          ↓         ↓
   (可能不同步) (可能过时) (可能偏离) (可能遗漏)

SDD流程：

规范定义 → 代码实现 → 自动验证
    ↑          ↑          ↑
  (单一事实来源) (实现规范) (确保一致)

在SDD中，规范是单一事实来源（Single Source of Truth），所有文档、代码、测试都围绕规范展开。

OpenSpec：解决增量开发核心问题的开源框架

增量开发 vs 全新开发

软件开发中，增量开发是更广泛的场景：

• 全新开发：从零开始，可以自由设计架构（0——>1)

• 增量开发：在现有系统上添加功能(1——>n)，需要：

  • 理解现有架构

  • 遵循现有规范

  • 与现有功能集成

  • 保持一致性

增量开发面临的挑战：

OpenSpec要解决的核心问题

OpenSpec框架专门针对增量开发场景设计，解决以下问题：

1. 规范的可发现性

问题：新功能开发者不知道系统有哪些能力，也不知道如何添加新功能。

OpenSpec解决方案：

• 所有能力（Capability）都在 specs/ 目录中明确定义

• 通过 openspec list –specs 可以快速查看所有能力

• 每个能力都有清晰的Purpose、Requirements和Scenarios

2. 变更的可追溯性

问题：需求变更时，不知道哪些代码、文档需要更新。

OpenSpec解决方案：

• 所有变更通过提案（Proposal）机制管理

• 变更提案明确说明影响范围（Affected specs、Affected code）

• 归档后，变更历史完整保留

3. 规范与代码的一致性

问题：代码实现后，文档往往不再更新，导致文档与代码不一致。

OpenSpec解决方案：

• 规范变更必须通过提案流程

• 实现完成后，规范自动更新（归档时合并）

• 规范中的场景（Scenarios）可以直接对应测试用例

4. AI助手的上下文理解

问题：AI助手缺乏项目上下文，无法准确理解需求。

OpenSpec解决方案：

• 规范提供结构化的上下文信息

• AI助手可以读取规范了解系统能力

• 变更提案提供清晰的实现指导

实战案例：从需求到实现的完整流程

让我们通过一个真实案例，看看OpenSpec如何在实际项目中发挥作用。

在一个已经存在的Agent工程中增加新的Agent

完整实战流程：

说明： openspec 的安装和初始化 (openspec init) 和SPEC KIT基本相同，非常简单，不赘述，本案例使用cursor 编辑器

第一步：创建变更提案

用户输入：

/openspec-proposal 生成一个写小说的智能体，核心是输入一个参考的优秀小说，使用langchain或langgraph框架。步骤包括：

执行逻辑

1.1 探索现有状态

首先，了解项目现状：

# 查看现有能力
openspec list –specs
# 输出：novel-writing-agent (不存在，需要新建)

# 查看活跃变更
openspec list
# 输出：无活跃变更

1.2 创建提案结构

选择变更ID：add-novel-writing-agent

创建目录结构：

openspec/changes/add-novel-writing-agent/
├── proposal.md      # 变更提案
├── design.md        # 技术设计
├── tasks.md         # 任务清单
└── specs/
    └── novel-writing-agent/
        └── spec.md  # 规范变更

1.3 编写提案文档

proposal.md：

# Change: Add Novel Writing Agent

## Why
用户需要一个智能体来分析参考小说并生成新的创意作品。
智能体应该能够从优秀的参考小说中提取关键元素（角色、情节、亮点、痛点），
并使用这些分析来创建新的短篇小说（8000-12000字），
具有相似结构但增强的亮点。

## What Changes
– **ADDED**: 小说写作智能体能力
– **ADDED**: 小说分析组件（提取角色、情节、亮点、痛点）
– **ADDED**: 情节转换组件（替换相似情节，增强亮点）
– **ADDED**: 小说生成组件（生成8000-12000字的短篇小说）
– **ADDED**: LangGraph工作流编排

## Impact
– **Affected specs**: 新能力 `novel-writing-agent`
– **Affected code**: 
  – 新智能体：`src/agents/novel_writing/`
  – 新工具：`src/agents/novel_writing/tools/`
  – 新提示词：`src/agents/novel_writing/prompts/`

1.4 编写技术设计

design.md（关键决策）：

## Decisions

### Decision: 使用LangGraph进行工作流编排
**理由**：
– 小说写作过程有清晰的顺序步骤和状态依赖
– LangGraph提供状态管理、检查点和条件路由
– 与现有框架架构（graph层）对齐

### Decision: 结构化分析输出格式
**理由**：
– 使用Pydantic模型进行类型安全和验证
– 使转换步骤更容易（结构化输入）
– 可以序列化/反序列化用于检查点

1.5 编写规范变更

specs/novel-writing-agent/spec.md：

## ADDED Requirements

### Requirement: 小说读取
系统应该从文件路径读取和解析markdown格式的参考小说。

#### Scenario: 读取有效的markdown小说
– **WHEN** 提供了有效的markdown文件路径
– **THEN** 系统读取文件内容并验证为markdown
– **AND** 返回小说内容以供处理

### Requirement: 小说分析
系统应该分析参考小说并提取结构化信息，包括主要角色、配角、核心情节、亮点和痛点。

#### Scenario: 提取角色信息
– **WHEN** 分析小说时
– **THEN** 系统识别并提取主要角色及其特征和角色
– **AND** 识别并提取配角及其关系

1.6 创建任务清单

tasks.md：

## 1. 框架：Graph层
– [ ] 1.1 创建graph状态模型
– [ ] 1.2 实现graph构建工具
– [ ] 1.3 创建graph节点定义

## 2. 数据模型
– [ ] 2.1 创建NovelAnalysis模型
– [ ] 2.2 创建Character模型
– [ ] 2.3 创建Highlight模型
– [ ] 2.4 创建PainPoint模型

## 3. 工具实现
– [ ] 3.1 创建read_novel工具
– [ ] 3.2 创建analyze_novel工具
– [ ] 3.3 创建transform_plot工具
– [ ] 3.4 创建generate_novel工具
…

1.7 验证提案

openspec validate add-novel-writing-agent –strict
# 输出：Change 'add-novel-writing-agent' is valid

第二步：实现变更

用户输入： /openspec-apply

执行逻辑

2.1 实现Graph层

根据任务清单，首先实现框架的Graph层：

# src/framework/graph/state.py
class GraphState(TypedDict, total=False):
    messages: List[Any]
    data: Dict[str, Any]
    errors: List[str]
    file_path: str
    novel_content: str
    target_words: int

2.2 实现数据模型

# src/models/novel_analysis.py
class Character(BaseModel):
    name: str
    traits: List[str]
    role: str
    relationships: List[str]

class NovelAnalysis(BaseModel):
    main_characters: List[Character]
    supporting_characters: List[Character]
    core_plot: str
    highlights: List[Highlight]
    pain_points: List[PainPoint]

2.3 实现工具

# src/agents/novel_writing/tools/read_novel.py
@tool
def read_markdown_novel(file_path: str) -> str:
    """读取markdown格式的小说"""
    # 实现文件读取和验证逻辑
    …

# src/agents/novel_writing/tools/analyze_novel.py
@tool
def analyze_novel(novel_content: str) -> Dict:
    """分析小说并提取结构化信息"""
    # 使用LLM进行分析
    …

# src/agents/novel_writing/tools/transform_plot.py
@tool
def transform_plot(analysis: Dict) -> str:
    """转换情节并增强亮点"""
    …

# src/agents/novel_writing/tools/generate_novel.py
@tool
def generate_novel(transformed_content: str, target_words: int = 10000) -> str:
    """生成新小说（8000-12000字）"""
    …

2.4 实现LangGraph工作流

# src/agents/novel_writing/graph.py
def build_novel_writing_graph():
    builder = GraphBuilder()
    
    # 添加节点
    builder.add_node("read", read_node)      # 读取小说
    builder.add_node("analyze", analyze_node)  # 分析小说
    builder.add_node("transform", transform_node)  # 转换情节
    builder.add_node("generate", generate_node)  # 生成新小说
    
    # 设置流程：read → analyze → transform → generate
    builder.set_entry_point("read")
    builder.add_edge("read", "analyze")
    builder.add_edge("analyze", "transform")
    builder.add_edge("transform", "generate")
    builder.add_edge("generate", END)
    
    return builder.build()

2.5 实现Agent

# src/agents/novel_writing/agent.py
class NovelWritingAgent(BaseAgent):
    def __init__(self, config: Optional[Dict] = None):
        # 初始化工具和提示词
        tools = [read_markdown_novel, analyze_novel, transform_plot, generate_novel]
        
        # 构建LangGraph工作流
        self.workflow = build_novel_writing_graph()
    
    def write_novel(self, file_path: str, target_words: int = 10000):
        # 执行工作流
        initial_state = {
            "file_path": file_path,
            "target_words": target_words,
            "data": {},
            "errors": []
        }
        final_state = self.workflow.invoke(initial_state)
        return final_state["data"]["generated_novel"]

2.6 更新任务状态

完成所有任务后，更新 tasks.md：

## 1. 框架：Graph层
– [x] 1.1 创建graph状态模型
– [x] 1.2 实现graph构建工具
– [x] 1.3 创建graph节点定义
…

第三步：归档变更

用户输入： /openspec-archive

执行逻辑

3.1 执行归档

openspec archive add-novel-writing-agent –yes

归档过程：

3.2 验证归档结果

# 验证规范
openspec validate –specs
# 输出：✓ spec/novel-writing-agent

# 查看新能力
openspec list –specs
# 输出：novel-writing-agent    requirements 6

完整流程总结

用户需求
   ↓
创建提案 (proposal.md, design.md, tasks.md, specs/)
   ↓
验证提案 (openspec validate)
   ↓
实现功能 (按照tasks.md顺序)
   ↓
更新任务状态 (标记完成)
   ↓
归档变更 (openspec archive)
   ↓
规范自动更新 (specs/novel-writing-agent/spec.md)

OpenSpec的优点

1. 解决增量开发的核心痛点

✅ 上下文可发现：新开发者（包括AI助手）可以快速了解系统能力

✅ 变更可追溯：每个功能都能追溯到对应的规范和提案 

✅ 规范与代码一致：归档时自动同步，确保一致性

✅ 知识可传承：规范作为项目知识库，团队成员离职不影响

2. AI友好的设计

✅ 结构化信息：规范提供清晰的上下文，AI助手易于理解 

✅ 自动化工具：CLI工具减少手动操作，提高效率

 ✅ 验证机制：自动检查格式和完整性，减少错误

 ✅ 标准化流程：提案→实现→归档的流程，AI助手易于遵循

3. 团队协作优势

✅ 统一规范：所有变更都遵循相同的规范格式

 ✅ 清晰沟通：提案文档明确说明Why、What、Impact 

✅ 减少冲突：通过规范检查，避免功能冲突

 ✅ 提高质量：规范中的场景直接对应测试用例

4. 长期维护优势

✅ 文档自动更新：归档时规范自动更新，无需手动维护 

✅ 历史完整保留：所有变更提案都保留在archive中

 ✅ 重构更安全：通过规范了解功能边界，重构时更安全 

✅ 扩展更容易：新功能可以基于现有规范进行扩展

OpenSpec的不足和未解决的问题

1. 规范维护成本

❌ 规范可能过时：如果实现与规范不一致，需要及时更新 

❌ 规范可能过于详细：过度规范化可能影响开发速度 

❌ 规范可能过于简单：规范不足可能导致实现偏差

缓解方案：

• 通过自动化验证确保一致性

• 平衡规范的详细程度

• 定期审查和更新规范

2. 未解决的问题

2.1 规范与实现的自动同步

问题：虽然归档时规范会更新，但实现过程中的临时不一致仍然可能发生。

现状：需要开发者手动确保实现符合规范。

未来可能：通过静态分析或运行时检查自动发现不一致。

2.2 规范的版本管理

问题：规范变更的历史版本管理可能不够完善。

现状：通过archive保留历史，但版本对比可能不够直观。

未来可能：提供规范的版本对比和diff功能。

4.3 大型项目的规范管理

问题：对于超大型项目，规范文件可能过多，管理复杂。

现状：通过目录结构组织，但可能不够灵活。

未来可能：提供规范的分层、分组、搜索等功能。

2.4 规范的测试生成

问题：虽然规范中的场景可以对应测试，但自动生成测试用例的能力有限。

现状：需要手动编写测试用例。

未来可能：基于规范自动生成测试用例框架。

总结：OpenSpec的价值定位

OpenSpec框架的核心价值在于解决增量开发中的规范管理问题。

适用场景

✅ 中型项目：需要清晰的规范管理 

✅ 团队协作：需要统一的变更流程 

✅ AI辅助开发：需要结构化上下文 

✅ 长期维护：需要知识传承和一致性

不适用场景

❌ 快速原型：时间紧迫的原型开发可能不需要完整规范 

❌ 个人项目：单人项目可能不需要如此严格的流程 

❌ 一次性脚本：简单的脚本不需要规范管理上述直接使用氛围编程

❌ 大型项目：产品复杂性高，规范对齐明确困难范式需要进一步完善和探索

核心理念

规范即真理，变更即提案，实现即归档

OpenSpec通过将规范作为单一事实来源，为增量开发提供了清晰的路径。虽然它不能解决所有问题，但在规范管理和团队协作方面，它确实提供了一个实用的解决方案。

这就是OpenSpec的价值所在。

SDD从概念到SPEC KIT的初步框架，到OpenSpec在增量开发的探索，我们看到范式在快速演进中，而且越来越具体，但是距离成熟可能还有很长的距离；而且AI范式和模型能力互为依赖，找到和当前模型能力匹配的范式是实际落地的关键，这还需要我们持续探索！

码字不容易，请点个关注，也欢迎关注我的公众号，系列文章如下：

1：AI重构研发范式：

AI时代，你最大的能力变迁：从“我不行”到“我能行”！

AI重构软件研发全流程走向落地！亚马逊发布「AI驱动开发」全新方法论，完整解读十大核心原则

AI开发新范式——规范驱动开发（SDD）【第三篇】：通过OpenSpec实现增量开发

一图介绍清楚基于Spec Kit 框架的SDD(规范驱动开发）的详细过程【SDD第二讲]

五分钟带你理解AI时代的软件研发新范式——SDD(规格驱动开发) 【SDD第一讲】

重温氛围编程：是AI开发的明日新星还是皇帝的新装

华为《智能世界2035》揭示软件未来：人机协同编程重塑软件开发格局

2：AI重构软件组织：

AI组织-未来已来：10年以后的组织是什么样子？

AI组织是什么样子？来自微软的最新分析 – The Year of the Frontier Firm:

3：软件工程本质思考：

AI时代，重新温习软件工程经典巨作，思考软件工程的本质

4： 模型本质的认识：

OpenAI深度揭秘大语言模型的幻觉本质

5： 软件智能测试：

AI在软件测试中的理想与现实：一场尚未到来的革命

6： AI实战

SDD开发实战：3小时从零构建可私有部署的AI助手