# 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年，清晰的规范文档能大幅降低新成员接手时的认知负担。

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

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

另外，建议增加一个环境变量关闭遥测：
```
OPENSPEC_TELEMETRY=0
```
## 初始化
进入项目的目录，执行
```
cd your-project
openspec init
```

OpenSpec会在项目根目录中创建`openspec`目录。第一次初始化的时候目录结构比较简单，但是后面随着迭代，目录会越来越复杂。目录结构说明如下：
```
项目根目录/
├── 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 个命令）**:

| 命令                            | 作用                                           |
| :---------------------------- | :------------------------------------------- |
| `/opsx:explore`               | 进入探索模式：在创建正式变更前，用于头脑风暴、调研技术方案或澄清需求，不会生成任何文件。 |
| `/opsx:propose <description>` | 一步到位地创建变更目录并生成所有必需的规划文件。                     |
| `/opsx:apply`                 | 按照 `tasks.md` 实现任务                           |
| `/opsx:archive`               | 完成并归档当前变更                                    |

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

| 命令                   | 作用                       |
| :------------------- | :----------------------- |
| `/opsx:new`          | 仅初始化变更目录结构，不创建文档         |
| `/opsx:continue`     | 按依赖顺序创建下一个文档（逐步模式）       |
| `/opsx:ff`           | 快进生成所有规划文档（一步到位）         |
| `/opsx:verify`       | 验证实现是否与规范一致              |
| `/opsx:sync`         | 将 Delta Spec 合并到主规范（不归档） |
| `/opsx:bulk-archive` | 批量归档多个已完成的变更             |
| `/opsx:onboard`      | 带教 15 分钟全流程引导，适合新手上手     |

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



---

> 作者: XiongNeng  
> URL: https://xiongneng.me/posts/ai/openspec/