从spec-kit到OpenSpec：规格驱动开发如何解决项目迭代痛点？

推荐语

OpenSpec让规格驱动开发更上一层楼，特别适合旧项目迭代和新功能开发的无缝衔接。

核心内容：
1. OpenSpec的核心特点：需求场景化、变更管理、增量式规格管理、严格验证机制
2. 与传统工具的区别：更结构化、场景驱动、更好的变更管理
3. 实际应用案例：GTD管理系统开发全过程复盘

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

因为spec-kit的爆火，“规格驱动开发”这个最新开发范式成为现在AI开发的一个新趋势。spec-kit在全新开发一个新的应用的方面，已经做到了极强的可控性，但是对于就项目的迭代开发，似乎并不理想。而OpenSpec似乎弥补了这一点的遗憾，它在就项目添加新功能方面提供了更好的支持。

最近我使用OpenSpec成功地完成了一个GTD（Getting Things Done）管理系统的核心功能开发。本文将详细介绍OpenSpec的核心特点、与传统工具的区别和优势，以及我们在实际项目中如何应用OpenSpec进行需求管理和开发实现的全过程复盘。

什么是OpenSpec？

OpenSpec是一个现代化的规格驱动开发工具，旨在帮助开发团队在编写代码之前先明确需求规格，通过结构化的需求文档和场景驱动的设计来提升软件质量和开发效率。

让AI用最简单的语言解释：

OpenSpec 可以理解为“公开的技术说明书”。就像乐高积木的拼接规则一样，它用文档明确告诉开发者：

1. 系统之间如何“对话”（比如手机APP和服务器）
2. 数据要按什么格式传递（比如文字/图片的排列方式）
3. 遇到错误该怎么处理

有了这份公开说明书，不同公司开发的软件就能像拼乐高一样无缝配合，不需要重复造轮子。

OpenSpec的核心特点

1. 需求场景化

OpenSpec强制要求每个需求必须包含具体的场景描述，使用标准的Gherkin格式，比如：

#### Scenario: 用户登录成功-**WHEN**用户输入有效的用户名和密码-**THEN**系统返回JWT令牌-**AND**用户跳转到主页面

2. 变更管理

通过三阶段工作流管理整个开发周期：

• Stage 1: 创建变更提案
• Stage 2: 实现变更
• Stage 3: 归档变更

3. 增量式规格管理

支持四种操作类型：

• ADDED - 新增功能需求
• MODIFIED - 修改现有需求
• REMOVED - 移除功能需求
• RENAMED - 重命名需求

4. 严格的验证机制

OpenSpec提供多层验证确保规格质量：

• 格式验证（Scenario标题、必需字段）
• 逻辑验证（需求完整性、场景覆盖）
• 语义验证（SHALL/MUST关键词使用）

OpenSpec与传统工具的区别和优势

与传统需求文档的区别

与其他规格驱动工具的比较

相比Cucumber/Behave

• 优势:
• 更轻量级，无需复杂的测试框架集成
• 专注于需求规格而非测试实现
• 更好的变更管理和版本控制
• 中文友好的设计

相比Swagger/OpenAPI

• 优势:
• 不仅限于API设计，覆盖所有功能需求
• 场景驱动的需求描述
• 更好的用户体验设计支持

相比JIRA等项目管理工具

• 优势:
• 结构化的需求规格
• 强制的场景思考
• 更好的技术债务管理
• 开发者友好的工具设计

OpenSpec的独特价值

1. 强制性思考

通过强制要求每个需求必须包含场景，促使开发者在编码前深入思考用户行为和系统响应。

2. 结构化沟通

为团队提供统一的沟通语言，减少需求理解的歧义，提升协作效率。

3. 可追溯性

从需求到实现的完整可追溯性，便于后期维护和功能回归。

4. 质量保证

通过提前发现需求缺陷和逻辑漏洞，减少后期重构成本。

实战案例复盘：GTD管理系统开发

今天我们通过OpenSpec成功地完成了GTD（Getting Things Done）管理系统的核心功能开发，以下是完整的操作复盘：

背景介绍

项目需求：开发一个基于GTD方法论的个人任务管理系统，支持7种任务状态流转和完整的任务管理功能。

操作流程

阶段1: 现状分析

# 1. 检查当前项目状态openspec list                          # 查看活跃变更openspec list --specs                  # 查看现有规格openspec validate --all               # 验证当前规格完整性

发现的问题：

• 存在一个已完成的变更 fix-tailwind-postcss-config需要归档
• 当前系统缺少完整的GTD功能规格定义

阶段2: 变更提案创建

基于GTD方法论，我们创建了 establish-gtd-foundation变更提案：

# 创建变更目录结构mkdir -p openspec/changes/establish-gtd-foundation/{specs/{task-management,ui-interaction,organization-management}}

提案结构：

• proposal.md - 阐述为什么要建立GTD基础功能
• tasks.md - 6个阶段的实现计划
• specs/ - 3个能力领域的规格变更

阶段3: 规格编写

我们编写了17个增量规格，覆盖三个核心能力领域：

任务管理 (8个需求)：

• 任务基础管理（创建、验证）
• 任务状态管理（7状态GTD工作流）
• 任务优先级管理（4级优先级）
• 任务时间管理（截止日期）
• 任务搜索和筛选
• 任务排序和重排

UI交互 (6个需求)：

• 任务列表界面设计
• 快速任务创建
• 任务表单交互
• 任务操作交互
• 响应式界面设计
• 加载和错误状态

组织管理 (3个需求)：

• 项目管理
• 上下文管理
• 组织结构查询

每个需求都包含具体的场景描述，例如：

#### Requirement: 系统**必须**支持7种GTD任务状态#### Scenario: 用户需要将任务从收件箱移动到下一步-**WHEN**用户点击任务的"下一步"按钮-**THEN**任务状态更新为"next"-**AND**状态变更时间戳记录当前时间

阶段4: 验证和修复

# 验证变更规格openspec validate establish-gtd-foundation --strict

遇到的问题和解决方案：

1. 格式问题：需求描述缺少MUST/SHALL关键词

• 解决：将所有"系统必须"改为"系统必须"

1. 提案文档问题：缺少"What Changes"部分

• 解决：补充完整的变更说明章节

阶段5: 实现开发

基于规格定义，我们实现了以下功能：

核心功能实现：

1. 7状态GTD工作流

• 实现了完整的任务状态转换
• 状态转换验证逻辑
• 可视化状态标签

1. 智能过滤系统

• 8个过滤选项（全部+7个状态）
• 实时任务计数更新
• 优雅的空状态处理

1. 上下文操作按钮

• 根据任务状态动态显示操作选项
• GTD方法论的状态转换指导
• 用户友好的按钮文案

1. 错误处理机制

• 统一的错误显示
• 可关闭的错误提示
• 网络请求错误处理

阶段6: 测试验证

使用Playwright进行端到端测试：

// 测试状态转换await page.getByRole('button',{ name:'开始处理'}).click();// 验证状态变化await expect(page.getByText('下一步')).toBeVisible();

测试覆盖：

• ✅ 任务创建和状态转换
• ✅ 过滤功能正确性
• ✅ 空状态处理
• ✅ 错误处理机制
• ✅ 用户界面响应性

阶段7: 归档完成

# 遇到CLI验证问题，手动归档mv openspec/changes/establish-gtd-foundation openspec/changes/archive/# 验证系统状态openspec validate --all  # ✅ 通过验证

经验总结

成功因素

1. 严格按照流程：遵循OpenSpec的三阶段工作流
2. 重视场景设计：每个需求都有具体的用户场景
3. 持续验证：开发过程中反复验证规格符合性
4. 工具集成：使用Playwright等工具进行自动化验证

改进空间

1. CLI工具稳定性：某些命令存在验证问题，需要手动干预
2. 模板丰富度：可以提供更多提案模板
3. 国际化支持：中文友好的设计很好，但可以进一步优化

最佳实践

1. 先规后码：严格按照规格驱动的方式进行开发
2. 场景思考：每个需求都要从用户角度思考具体场景
3. 持续验证：开发过程中不断对照规格进行验证
4. 文档同步：及时更新项目文档，保持规格与实现的一致性

结论

OpenSpec通过结构化的需求规格和场景驱动的设计，为软件开发提供了一种更加可靠和高效的开发方式。

OpenSpec特别适合那些需求复杂、质量要求高的软件项目。虽然初期需要一定的学习成本，但长期来看，这种规格驱动的开发方式能够显著提升软件开发的整体质量和效率。

对于希望提升软件开发质量的团队来说，OpenSpec是一个值得尝试的工具。它不仅仅是一个需求管理工具，更是一种开发方法的革新，帮助团队建立起从需求到实现的完整可追溯性。