OpenSpec 是一个专为 AI 编程场景设计的规范驱动开发（Spec-Driven Development, SDD）框架。它能有效解决 AI 编程中常见的"猜需求"和"代码偏离设计"问题------在编写任何代码前，让 AI 与人对"要构建什么"达成明确共识。
核心定位：与你现有工具的分工
OpenSpec 和你之前熟悉的 API 契约工具（如 OpenAPI YAML、gRPC Proto）定位不同，两者是互补关系：
| 对比维度 | OpenSpec（功能契约） | OpenAPI / gRPC（技术契约） |
|---|---|---|
| 核心目的 | 定义业务功能：为什么做、做什么、验收标准是什么 | 定义技术接口：URL、参数类型、返回值结构 |
| 文件格式 | Markdown（.md） | YAML / .proto |
| 生成对象 | 需求文档、设计文档、任务清单 | Controller 接口、DTO、客户端 Stub |
| 工作流阶段 | 开发之前（需求→设计） | 开发之中（设计→编码） |
简单说，OpenSpec 帮你想清楚"做什么"，OpenAPI/gRPC 帮你约定"怎么做"。
OpenSpec 的核心理念与目录结构
三个核心概念
- Specs（规范） ：
openspec/specs/目录下存放的是当前系统已构建内容的真实来源，即已经确定的功能规范。 - Changes（变更） ：
openspec/changes/目录下存放的是对未来的提案------每次新增功能、修复 Bug 或重构，都创建一个独立的变更文件夹，包含提案、任务和规范增量。 - Archive（归档） ：变更完成后，会被归档到
openspec/changes/archive/，其规范增量会自动合并到主 Specs 中，保持规范与代码同步。
标准目录结构
your-project/
├── openspec/
│ ├── config.yaml # 项目配置（技术栈、约定规则等）
│ ├── specs/ # 当前系统的"真理"：已构建的功能规范
│ │ └── [capability]/
│ │ └── spec.md # 需求 + 验收场景
│ └── changes/ # 提案：计划要做的变更
│ ├── [change-name]/
│ │ ├── proposal.md # 为什么改、改什么、影响范围
│ │ ├── design.md # 技术决策（可选）
│ │ ├── tasks.md # 实施任务清单
│ │ └── specs/ # 规范增量（ADDED/MODIFIED/REMOVED）
│ └── archive/ # 已完成的变更如何在 SDD 模式中使用 OpenSpec
结合你的 SpringBoot + MyBatis-Plus 技术栈，完整工作流分为 4 步：
第一步：安装与初始化
前置条件：Node.js >= 20.19.0。
bash
# 1. 全局安装 OpenSpec CLI
npm install -g @fission-ai/openspec@latest
# 2. 在项目根目录初始化
cd your-springboot-project
openspec init初始化时会提示选择 AI 工具（如 Cursor、Claude Code、GitHub Copilot），OpenSpec 会自动生成对应的斜杠命令配置文件。
初始化完成后，建议填充 openspec/config.yaml 的 context 字段，写明项目技术栈（SpringBoot、MyBatis-Plus）、编码规范等，让 AI 每次规划时都基于项目上下文。
第二步：起草变更提案（/opsx:propose）
在 AI 编程工具中输入斜杠命令，开始一个新功能：
/opsx:propose 新增订单创建功能，支持用户提交订单、扣减库存、生成订单记录AI 会自动创建 openspec/changes/add-order-creation/ 目录，并生成以下文件：
-
proposal.md：描述变更原因、内容和影响范围。 -
specs/order-management/spec.md：用 Given/When/Then 格式定义验收场景：markdown## Requirement: 订单创建 系统应接受用户订单请求并生成订单记录。 #### Scenario: 库存充足时创建订单成功 - GIVEN 用户ID为 "U10001"，商品 "P001" 库存为 10 - WHEN 用户提交购买数量为 3 的订单 - THEN 订单状态为 "待支付"，库存扣减为 7 -
tasks.md：拆解为可执行的实施任务清单（如"1.1 实现 OrderService.createOrder 事务方法"）。 -
design.md（可选）：记录技术决策，如是否使用分布式事务、消息队列等。
第三步：审阅与对齐（人工 Review）
在 AI 编写代码前，人工审阅这些 markdown 文件：
- 需求是否完整、准确？
- 验收场景是否覆盖边界情况？
- 技术决策是否合理？
这个阶段修改成本极低------改几行文档比改代码快得多。确认无误后，进入实施阶段。
第四步：实施变更（/opsx:apply）
执行命令让 AI 按规范编码：
/opsx:apply add-order-creationOpenSpec 按 tasks.md 逐项推进，AI 会读取规范文件并生成对应的 Java 代码：Controller、Service、Mapper、Entity、MapStruct 转换器等。每完成一个任务，tasks.md 自动打勾。
此时，你之前定义的 OpenAPI YAML 或 gRPC Proto 仍然发挥作用------OpenSpec 生成的是业务规范，API 契约文件仍然用于生成接口骨架和 DTO。
第五步：归档变更（/opsx:archive）
所有任务完成后，执行归档：
/opsx:archive add-order-creation归档动作会：
- 将变更的
specs/合并到主openspec/specs/目录。 - 将整个变更文件夹移动到
openspec/changes/archive/。
至此，这个功能的规范成为项目"真理"的一部分，供后续变更查阅和参考。
与传统 SDD（API 契约）的分工闭环
在你的 SpringBoot 项目中，OpenSpec 和 OpenAPI/gRPC 可以形成完整闭环：
┌─────────────────────────────────────────────────────────────────┐
│ OpenSpec 工作流（业务契约） │
│ /opsx:propose → 审阅 → /opsx:apply → /opsx:archive │
│ 产出：proposal.md, tasks.md, specs/*.md（验收场景） │
└──────────────────────────┬──────────────────────────────────────┘
│ 明确了"做什么"
▼
┌─────────────────────────────────────────────────────────────────┐
│ 技术契约定义（API 契约） │
│ 手写 / 生成 OpenAPI YAML 或 gRPC Proto │
│ 产出：接口路径、参数类型、返回值结构 │
└──────────────────────────┬──────────────────────────────────────┘
│ 明确了"怎么做"
▼
┌─────────────────────────────────────────────────────────────────┐
│ 代码生成与实现（SpringBoot + MyBatis-Plus） │
│ openapi-generator / protobuf-maven-plugin → 生成骨架 │
│ 开发者填充业务逻辑、MapStruct 转换、事务管理 │
└─────────────────────────────────────────────────────────────────┘总结
OpenSpec 不是用来替代 OpenAPI 或 gRPC Proto 的，而是在它们之前 增加了一层业务功能契约。它让 AI 编程从"猜需求"转变为"按规范执行"，将需求、设计、验收条件结构化地管理起来，并留下完整的变更历史。
在我们熟悉的 SpringBoot + MyBatis-Plus 项目中，使用路径是：先用 OpenSpec 敲定功能规范和任务清单，再用 OpenAPI/gRPC 定义技术接口，最后让 AI 按规范生成并填充业务代码。