OpenSpec实现SDD开发模式

OpenSpec是一个规范驱动开发（Spec-Driven Development，SDD）框架，转为AI编程助手设计。它通过在编写代码之前先定义规范，确保人与AI对需求的理解达成一致。

由于AI辅助编程工具的交互方式、智能程度、交付能力差异巨大，每个开发者的使用体验也不一样，适应习惯也有很大的差异，所以团队内没必要限制只使用某个工具。OpenSpec支持22种工具，可以同时在这些工具中开发同一个项目，避免因切换工具开发代码，需要对Spec进行迁移。

GitHub地址：https://github.com/Fission-AI/openspec

什么是规范驱动开发

传统开发流程通常是：需求 → 直接编码 → 测试 → 交付。 规范驱动开发的流程是：需求 → 编写规范 → 验证规范 → 编码实现。

这种方式的优势在于：

• 人与AI先对“做什么”达成一致，避免返工。
• 规范文档作为契约，减少沟通成本。
• 规范可以版本化管理，便于追溯。

核心理念：

• 动态性：文档可以随时更新，没有严格的阶段门槛
• 迭代而非瀑布：支持增量添加需求，逐步完善
• 简单：只需要Markdown文档，无复杂工具链
• 兼顾存量和新建项目：既适用于已有代码库（Brownfield），也适用于全新项目（Greenfield）

OpenSpec模式

核心理念：设计即真理。代码是规范的衍生品而非源头。遵循“先想清楚再落笔”的工程原则。

OpenSpec工作流：

• 编写详尽的技术规范（API定义、状态机、边界条件）
• 团队评审规范，达成共识
• 生成骨架代码，编写测试
• 实现业务逻辑，验证符合规范

使用场景：

• 大型团队协作：前后端、数据组、移动端并行开发，OpenSpec充当了可执行的“合同”
• 核心基础设施：支付系统、中间件、底层库。这类场景错误成本极高，需要再编码前进行形式化验证。
• 合规与审计严苛的项目：金融、医疗、军工领域，需要追溯“需求→规范→代码”的完整链条，文档是核心交付件。
• 长期维护项目：当项目生命周期超过3-5年，清晰的规范文档能大幅降低新成员接手时的认知负担。

优势和劣势：

• √确定性高：返工率低，逻辑边界清晰，生成自动化测试（如契约测试）非常方便
• √可并行：前后端仅依赖规范，无需互相等待
• ×前期开销大：在需求未验证时需要投入大量时间写文档，
• ×抗变弱：面对频繁变更的需求，维护规范与代码同步的成本很高。

安装

1
2
3
4
5

npm install -g @fission-ai/openspec@latest
# 查看版本
openspec --version
# 查看帮助信息
openspec --help

另外，建议增加一个环境变量关闭遥测：

1

OPENSPEC_TELEMETRY=0

初始化

进入项目的目录，执行

1
2

cd your-project
openspec init

OpenSpec会在项目根目录中创建openspec目录。第一次初始化的时候目录结构比较简单，但是后面随着迭代，目录会越来越复杂。目录结构说明如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

项目根目录/
├── openspec/                     # OpenSpec 核心工作目录
│   ├── config.yaml               # 项目级全局配置与 AI 上下文注入
│   ├── specs/                    # 稳定规范目录（唯一真相源 / Single Source of Truth）
│   │   ├── <capability>/         # 按能力领域划分的文件夹（如 auth/、payments/）
│   │   │   └── spec.md           # 具体的系统行为与能力规范
│   │   └── .gitkeep
│   ├── changes/                  # 活跃的变更提案目录
│   │   └── <change-name>/        # 单个功能或 Bug 修复的变更文件夹（如 add-2fa/）
│   │       ├── proposal.md       # 提案说明（Why & What，验证器强制检查）
│   │       ├── design.md         # 技术实现方案（架构、数据流、接口设计等）
│   │       ├── tasks.md          # 实现任务清单
│   │       └── specs/            # 增量规范（Delta Spec，描述本次变动的规则修改）
│   │           └── <capability>/
│   │               └── spec.md
│   └── archive/                  # 已完成并归档的历史变更目录（可选）
└── .claude/ 或其他AI工具目录/    # 根据初始化的AI工具（如 Claude、Cursor 等）生成的斜杠命令与 Skills 文件

注意：openspec init 会根据你选择的 AI 工具，在对应目录生成命令和 Skills 文件。例如，选择 Claude Code 则生成 .claude/commands/opsx/ 和 .claude/skills/，选择 Qoder 则生成 .qoder/commands/opsx/ 和 .qoder/skills/

核心工作流

OpenSpec提供了十几个OPSX斜杆命令命令执行不同的任务。

默认 Core 配置（常用 4 个命令）:

扩展工作流命令（通过 openspec config profile 开启）

最佳实践

在一个大型项目开发过程中，任何特性的增删改，都应该走一遍change流程。如果只是bug修改或者内部实现优化（如性能、重构），并且不影响系统的可观察行为（API、UI、业务规则），则可以直接修改代码，不需要创建变更。