OpenSpec：轻量级AI工程规范管理框架

前言

在《SDD规范驱动开发：AI时代的软件工程新范式》一文中，我们详细介绍了SDD（Spec-Driven Development，规范驱动开发）的设计思想：以规范为核心驱动代码生成，在编写任何代码之前先让人与AI达成明确共识，从根本上解决AI编程中的上下文漂移、决策不透明、知识无法沉淀等工程痛点。

OpenSpec 是一款将SDD方法论工程化落地的开源工具。它不是另一套复杂的项目管理系统，而是一个轻量级的规范层：通过简洁的目录结构和斜杠命令，将每次特性开发组织为包含提案、规范、设计、任务清单的结构化变更单元，配合20+种主流AI助手开箱即用，帮助开发者在保持工程纪律的同时不增加额外的流程负担。

什么是OpenSpec

OpenSpec的官方定义是：

The most loved spec framework.

其设计哲学可以概括为五条原则：

→ fluid not rigid         (流动而非刚性)
→ iterative not waterfall (迭代而非瀑布)
→ easy not complex        (简单而非复杂)
→ built for brownfield    (面向存量系统而非只支持新项目)
→ scalable                (从个人项目到企业级均可适用)

OpenSpec通过在项目中引入一个openspec/目录，将每次特性开发或变更组织为包含提案、规范、设计、任务清单的结构化文件夹。配合AI助手的斜杠命令，开发者可以在几秒内启动一次规范化的变更流程，而不是直接让AI开始写代码。

与同类工具的对比

工具	定位	核心差异
`OpenSpec`	轻量级规范层，多工具支持	流程灵活、支持`20+`种`AI`助手、开箱即用
`Spec-kit`（GitHub）	重量级`SDD`工具包	功能完整但流程较重，需要更多配置
`Kiro`（AWS）	专属`IDE`集成	功能强大但锁定`IDE`和`Claude`模型
无规范	直接`Vibe Coding`	快速启动但结果不可预测

核心概念

理解OpenSpec的工作原理，需要掌握以下几个核心概念。

Specs（规范，系统的事实来源）

specs/目录是整个项目的"行为事实来源"（source of truth），描述系统当前的行为方式。它按领域组织：

openspec/specs/
├── auth/
│   └── spec.md       # Authentication behavior
├── payments/
│   └── spec.md       # Payment processing
└── ui/
    └── spec.md       # UI behavior

规范文件采用结构化的需求格式，使用SHALL/MUST/SHOULD等RFC 2119关键字表达需求强度，并通过Given/When/Then场景使需求可验证。

Changes（变更，每个特性独立管理）

每一次特性开发或变更都对应changes/下的一个独立文件夹，包含该变更所需的全部上下文信息：

openspec/changes/add-dark-mode/
├── proposal.md        # Why and what
├── design.md          # How (technical approach)
├── tasks.md           # Implementation checklist
└── specs/             # Delta specs (what's changing)
    └── user-http-service/
        └── spec.md

这种"变更即文件夹"的设计带来了几个工程优势：多个变更可以并行进行而不互相污染；归档后的变更保留完整上下文，支持历史追溯；变更文件夹也是天然的代码审查单元。

Delta Specs（增量规范）

想象一下，你和一个工程师对接需求时，不会让他读完整个系统文档，而是直接告诉他"这次迭代新增了什么、改了什么、去掉了什么"。增量规范的作用就是这样——它是每次变更专属的行为变更清单，存放在变更文件夹的specs/<domain>/spec.md中，只描述本次变更对系统行为的增量影响，而非重写整份规范。

增量规范使用三个标记描述变更类型：

ADDED：本次新增的行为需求
MODIFIED：本次修改的既有行为（标注旧值）
REMOVED：本次移除的行为（标注移除原因）

每条需求以Given/When/Then场景格式表达，确保需求是可验证的而非模糊的描述。以用户服务为例：

## ADDED Requirements

### Requirement: Create User
The system SHALL create a new user record when provided with valid registration data.

#### Scenario: Successful user creation
- WHEN a POST request is sent to /api/v1/users with valid username, email and password
- THEN the system SHALL return HTTP 200 with the new user's id
- AND the user record SHALL be persisted in the database

#### Scenario: Duplicate email
- WHEN a POST request is sent with an email already in use
- THEN the system SHALL return HTTP 400

增量规范在工作流中扮演"行为合同"的角色，贯穿整个变更生命周期的三个环节：

驱动实现：/opsx:apply执行时，AI以增量规范为基准，确保生成的代码满足每条场景定义的行为约束
驱动验证：/opsx:verify执行时，AI逐条核查代码实现是否与增量规范中的Given/When/Then场景一致
沉淀为永久规范：/opsx:archive执行时，ADDED需求追加到主规范，MODIFIED需求替换旧版本，REMOVED需求从主规范中移除，确保openspec/specs/始终反映系统的当前行为

这种设计的核心价值在于：AI不是凭感觉猜测你想要什么，而是按照明确的行为合同来实现和验证——需求、实现、验证三者形成闭环。

Artifacts（工件，驱动实现的文档体系）

变更文件夹中的文档（工件）构成了一个相互依赖的信息体系，引导AI从意图到实现：

proposal ──► specs ──► design ──► tasks ──► implement
  (why)      (what)    (how)     (steps)

工件	文件	作用
提案	`proposal.md`	记录变更动机、范围边界、整体思路
增量规范	`specs/<domain>/spec.md`	描述行为层面的变化（不涉及实现细节）
设计	`design.md`	技术方案、架构决策、数据流设计
任务清单	`tasks.md`	具体实现步骤，支持逐条执行和验证

支持的AI工具

OpenSpec支持20+种主流AI编程助手，通过openspec init即可自动为所选工具生成对应的斜杠命令文件：

AI助手	命令文件路径
`Claude Code`	`.claude/commands/opsx/<id>.md`
`GitHub Copilot`	`.github/prompts/opsx-<id>.prompt.md`
`Cursor`	`.cursor/commands/opsx-<id>.md`
`Windsurf`	`.windsurf/workflows/opsx-<id>.md`
`Gemini CLI`	`.gemini/commands/opsx/<id>.toml`
`Amazon Q`	`.amazonq/prompts/opsx-<id>.md`
`Continue`	`.continue/prompts/opsx-<id>.prompt`
`Qwen Code`	`.qwen/commands/opsx-<id>.toml`

核心工作流命令

OpenSpec通过 Profile（配置模式） 控制安装哪些斜杠命令，共有两种Profile。

默认快捷路径（core profile）

openspec init默认安装core profile，只生成以下4个命令，适合大多数日常开发场景：

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:archive

命令	作用
`/opsx:explore [topic]`	探索性思考，不创建变更文件夹
`/opsx:propose <name>`	一步生成变更文件夹及全部规划工件
`/opsx:apply`	按`tasks.md`逐条实现
`/opsx:archive`	归档变更，合并增量规范到主规范

扩展工作流（expanded profile）

如需更细粒度的控制，可以切换到custom profile，从全部11个命令中按需选择安装：

# 切换到 custom profile 后重新初始化
openspec config profile custom
openspec init

custom profile在core的基础上新增了以下命令：

/opsx:new ──► /opsx:ff (或 /opsx:continue) ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

命令	作用
`/opsx:new <name>`	创建变更文件夹脚手架（不自动生成工件内容）
`/opsx:continue`	按依赖关系逐步生成下一个工件
`/opsx:ff`	快进：一次性生成所有规划工件
`/opsx:verify`	验证实现是否与增量规范一致
`/opsx:sync`	将增量规范合并到主规范（不归档变更文件夹）
`/opsx:bulk-archive`	批量归档多个已完成的变更
`/opsx:onboard`	交互式教程，引导完整工作流

Profile配置保存在全局配置~/.config/openspec/config.json中，切换后执行openspec init即可重新生成对应的斜杠命令文件。

安装与初始化

安装OpenSpec CLI

OpenSpec通过npm发布，需要Node.js 20.19.0或更高版本：

# 全局安装
npm install -g @fission-ai/openspec@latest

# 也支持 pnpm / yarn / bun
pnpm add -g @fission-ai/openspec@latest

在项目中初始化

进入项目目录，运行初始化命令：

cd your-project
openspec init

初始化过程是交互式的，会询问：

选择要配置的AI工具（可多选）
选择工作流配置（core默认快捷路径，或custom扩展工作流）

以选择Claude Code为例，初始化完成后项目新增以下结构：

your-project/
├── .claude/                              # Claude Code 集成目录
│   ├── commands/
│   │   └── opsx/                         # OpenSpec 斜杠命令
│   │       ├── apply.md                  # /opsx:apply 命令定义
│   │       ├── archive.md                # /opsx:archive 命令定义
│   │       ├── explore.md                # /opsx:explore 命令定义
│   │       └── propose.md                # /opsx:propose 命令定义
│   └── skills/
│       ├── openspec-apply-change/        # apply 工作流的行为指导技能
│       ├── openspec-archive-change/      # archive 工作流的行为指导技能
│       ├── openspec-explore/             # explore 工作流的行为指导技能
│       └── openspec-propose/             # propose 工作流的行为指导技能
└── openspec/                             # OpenSpec 核心规范目录
    ├── changes/                          # 进行中的变更（每个变更一个子目录）
    │   └── archive/                      # 已归档的历史变更记录
    ├── specs/                            # 系统行为规范（事实来源，初始为空）
    └── config.yaml                       # OpenSpec 项目配置

如果是选择了其他工具（如GitHub Copilot、Cursor等），相应的命令定义和技能文件会被生成到对应的集成目录中，使用方式与上述类似。

实战演示：使用GoFrame构建用户服务

下面通过一个完整的实例，演示如何使用OpenSpec进行AI工程管理实践：用GoFrame框架从头构建一个用户服务，提供以下RESTful接口：

方法	路径	说明
`POST`	`/api/v1/users`	创建用户
`GET`	`/api/v1/users`	查询用户列表（支持分页）
`GET`	`/api/v1/users/{id}`	按`ID`查询用户
`PUT`	`/api/v1/users/{id}`	更新用户（支持部分更新）
`DELETE`	`/api/v1/users/{id}`	删除用户

第一步：探索需求

在开始正式规划之前，先用/opsx:explore澄清技术选型和边界，执行以下指令开始：

/opsx:explore

随后给AI自己的需求：

我要用 GoFrame 框架构建一个用户服务，提供 RESTful CRUD 接口。数据库还没确定，SQLite 还是 MySQL？

随后根据和AI的多次交互逐步澄清需求和技术选型。

探索阶段不会创建任何文件，纯粹是对齐认知的过程。

第二步：提案与规划

需求清晰后，可以手动使用/opsx:propose一步生成完整的变更规划工件：

/opsx:propose user-http-service

也可以通过自然语言告诉AI继续执行，它会自动调用该指令完成该步骤操作。

OpenSpec第二步：提案与规划

生成的4个工件及其作用如下：

工件	作用
`proposal.md`	记录本次变更的动机（为什么做）、范围边界（做什么、不做什么）和整体思路，是后续工件的出发点
`specs/user-crud/spec.md`	增量规范（行为合同）：使用`ADDED`/`MODIFIED`/`REMOVED`标记描述本次变更对系统行为的增量影响，以`Given/When/Then`场景定义可验证的需求条件。它是整个变更的核心基准 - `/opsx:apply`按它驱动代码实现，`/opsx:verify`按它核查实现是否达标，`/opsx:archive`按它更新主规范
`design.md`	技术实现方案，包含架构决策、技术选型理由、数据流设计等，是任务拆解的依据
`tasks.md`	将设计方案拆解为可逐条执行的实现清单，`/opsx:apply`将按此清单驱动`AI`逐步完成实现

在进入实现之前，你可以直接编辑这些工件进行调整，AI的实现将完全以修改后的工件为准。这是OpenSpec规范先行理念的核心体现。

OpenSpec第二步：提案与规划，生成的文档

第三步：实现

工件确认无误后，运行/opsx:apply驱动AI按任务清单逐步实现：

/opsx:apply

也可以通过自然语言要求AI开始实现。

实现过程中如果发现设计需要调整，可以随时暂停，在更新工件中的任意内容后，再继续执行，AI会根据更新后的工件继续工作。

第四步：验证（扩展工作流）

如果启用了扩展工作流，可以在归档前使用/opsx:verify验证实现是否与规范一致，如果使用的是默认的core profile，那么该步骤将在/opsx:apply过程中自动进行。

/opsx:verify

以下是对五个接口的实际验证示例：

# 创建用户
curl -s -X POST http://127.0.0.1:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","email":"alice@example.com","password":"secret123"}'
# {"code":0,"message":"","data":{"id":1}}

# 查询用户列表
curl -s "http://127.0.0.1:8080/api/v1/users?page=1&pageSize=10"
# {"code":0,"message":"","data":{"list":[{"id":1,"username":"alice","email":"alice@example.com",...}],"total":1}}

# 按 ID 查询（password 字段不出现）
curl -s http://127.0.0.1:8080/api/v1/users/1
# {"code":0,"message":"","data":{"id":1,"username":"alice","email":"alice@example.com",...}}

# 部分更新
curl -s -X PUT http://127.0.0.1:8080/api/v1/users/1 \
  -H "Content-Type: application/json" \
  -d '{"username":"alice2"}'
# {"code":0,"message":"","data":{}}

# 删除用户
curl -s -X DELETE http://127.0.0.1:8080/api/v1/users/1
# {"code":0,"message":"","data":{}}

第五步：归档

验证通过后，运行/opsx:archive完成整个变更周期：

/opsx:archive

归档操作会依次完成两件事：

合并增量规范到主规范：将changes/user-http-service/specs/下的增量规范按ADDED/MODIFIED/REMOVED规则合并到openspec/specs/，使主规范与代码的当前行为保持一致
移动变更文件夹：将changes/user-http-service/整体移入changes/archive/，从活跃变更列表中清除，同时完整保留本次变更的提案、设计、任务清单等所有上下文，支持日后追溯

OpenSpec第五步：归档

归档后，openspec/specs/user-crud/spec.md就成为了用户服务行为的永久记录。下次任何人——无论是新成员还是AI——都可以通过读取specs/来理解系统当前的行为，而不需要翻历史聊天记录。

需要注意的是，归档是一个纯文档操作，不涉及任何代码文件，跳过这一步不会影响程序运行。但如果长期不执行归档，openspec/specs/会与代码实际行为产生偏差，openspec list中也会堆积大量已完成但未归档的"活跃变更"，最终导致OpenSpec的规范管理价值逐渐失效。

CLI管理命令

除了斜杠命令，OpenSpec还提供了一套CLI命令用于日常管理：

# 列出所有活跃变更
openspec list

# 查看某个变更的详情
openspec show user-http-service

# 验证规范格式
openspec validate user-http-service

# 启动交互式仪表盘
openspec view

# 更新项目中的 AI 工具配置
openspec update

CLI命令速查表

命令	作用
`openspec init`	初始化项目，配置`AI`工具集成
`openspec update`	刷新`AI`工具配置，同步最新斜杠命令
`openspec list`	列出活跃变更和规范
`openspec show <name>`	查看变更或规范的详细内容
`openspec validate <name>`	检查规范格式和结构问题
`openspec view`	打开交互式仪表盘
`openspec archive <name>`	从终端归档已完成的变更
`openspec status`	查看当前变更的工件进度
`openspec config profile`	切换工作流配置（`core`/`custom`）

总结

OpenSpec提供了一种轻量而实用的方式来解决AI编程中最棘手的工程管理问题：如何在飞速的代码生成中保持工程纪律，如何让需求、设计、实现三者保持一致，如何让每一次技术决策都有迹可循。

它的核心价值不是增加流程负担，而是通过结构化的规范层，让人和AI在动手写代码之前先达成共识——先对齐，再实现。

对于正在构建AI辅助开发工作流的团队，OpenSpec是一个值得纳入工程工具箱的选择：安装简单、工具兼容性强、工作流灵活，并且完全开源（MIT协议）。

参考资料

OpenSpec GitHub 仓库

前言​

什么是OpenSpec​

与同类工具的对比​

核心概念​

Specs（规范，系统的事实来源）​

Changes（变更，每个特性独立管理）​

Delta Specs（增量规范）​

Artifacts（工件，驱动实现的文档体系）​

支持的AI工具​

核心工作流命令​

默认快捷路径（core profile）​

扩展工作流（expanded profile）​

安装与初始化​

安装OpenSpec CLI​

在项目中初始化​

实战演示：使用GoFrame构建用户服务​

第一步：探索需求​

第二步：提案与规划​

第三步：实现​

第四步：验证（扩展工作流）​

第五步：归档​

CLI管理命令​

CLI命令速查表​

总结​

参考资料​

前言