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

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

引言：AI编程的痛点

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

回顾 SDD：规范即真理

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

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

1. 规范定义行为：系统的行为由规范（Specification）明确定义

2. 代码实现规范：代码是对规范的实现，而非规范的替代

3. 规范驱动变更：所有变更都从规范变更开始

4. 规范即文档：规范既是需求文档，也是设计文档

SDD vs 传统开发

传统开发流程：

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

SDD流程：

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

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

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

增量开发 vs 全新开发

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

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

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

  • 理解现有架构

  • 遵循现有规范

  • 与现有功能集成

  • 保持一致性

增量开发面临的挑战：

1. 上下文缺失：新功能开发者（包括AI）不了解现有系统

2. 规范不一致：不同时期开发的功能可能遵循不同规范

3. 变更管理混乱：需求变更时，文档、代码、测试更新不同步

4. 知识传承困难：团队成员离职后，项目知识难以传承

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. 读取优秀小说（md格式）

2. 总结分析，包括主角，配角，核心情节，爽点和痛点等

3. 以总结的内容替换为相似的情节，增加更多的爽点

4. 生成一篇新的小说（短篇小说 8000-12000字）

执行逻辑

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

归档过程：

1. 将变更目录移动到archive/2025-11-22-add-novel-writing-agent/

2. 将规范变更合并到specs/novel-writing-agent/spec.md

3. 系统现在有了novel-writing-agent能力

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助手