OpenSpec

OpenSpec 是一个面向 AI 编码助手的轻量级 spec framework。它的核心目标不是增加流程负担，而是在真正开始写代码之前，先把“要改什么、为什么改、如何验收”沉淀成结构化产物，让人和 AI 在同一份规格上协作。

1. OpenSpec 解决什么问题

AI 编码助手很擅长生成代码，但如果需求只存在于对话上下文里，就很容易出现这些问题：

• 需求边界不清，越写越偏
• 对话一长，前面的约束被遗忘
• 多次迭代后，很难知道系统“当前到底应该如何工作”
• 变更做完之后，缺少可以审查和归档的规格记录

OpenSpec 的思路是：把“当前系统如何工作”和“这次准备改什么”分开管理。

初始化之后，项目里会出现这样一套结构：

openspec/
├── specs/                 # 当前系统行为，source of truth
│   └── <domain>/spec.md
├── changes/               # 每次变更一个目录
│   └── <change-name>/
│       ├── proposal.md    # 为什么做、改什么
│       ├── design.md      # 技术方案
│       ├── tasks.md       # 实现清单
│       └── specs/         # delta specs，描述这次变更
│           └── <domain>/spec.md
└── config.yaml            # 项目配置

其中最关键的是两类目录：

• openspec/specs/：主规格，描述系统当前已经成立的行为
• openspec/changes/：变更规格，每个 change 单独记录 proposal、design、tasks 和 delta specs

当一个 change 完成并归档后，delta specs 会合并回主规格，变更目录则移动到 openspec/changes/archive/ 中，方便后续追溯。

2. 核心概念

2.1 Artifacts

OpenSpec 把一次变更拆成几个彼此衔接的 artifacts：

Artifact	作用
proposal.md	说明为什么做、准备改什么、范围是什么
specs/	描述需求变化本身，通常按 ADDED / MODIFIED / REMOVED 编写
design.md	说明怎么实现、涉及哪些技术决策
tasks.md	把实现拆成可执行的 checklist

它们之间通常是这样衔接的：

proposal -> specs -> design -> tasks -> implement

但 OpenSpec 的理念不是“瀑布式阶段门”，而是边做边修正。实现过程中如果发现设计不合理，可以回过头补 proposal、更新 specs、调整 design，再继续执行。

2.2 Delta Specs

Delta spec 是 OpenSpec 里最重要的概念。它不直接重写整份系统规格，而是明确说明“这次 change 相对现状改了什么”。

典型格式如下：

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication

The system MUST require a second factor during login.

#### Scenario: OTP required

- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout

The system SHALL expire sessions after 30 minutes of inactivity.

## REMOVED Requirements

### Requirement: Remember Me

Deprecated in favor of 2FA.

归档时的处理规则也很直接：

• ADDED：追加到主规格
• MODIFIED：替换主规格中的旧版本
• REMOVED：从主规格中删除

3. 安装与初始化

3.1 环境要求

根据当前 README，OpenSpec 需要：

• Node.js 20.19.0 或更高版本

3.2 安装 CLI

官方推荐全局安装：

npm install -g @fission-ai/openspec@latest
openspec --version

README 也说明它同样可以配合 pnpm、yarn、bun 和 nix 使用，但最常见的上手方式还是 npm install -g。

3.3 初始化项目

进入你的项目目录后执行：

cd your-project
openspec init

如果你想非交互地指定 AI 工具，可以直接传 --tools：

openspec init --tools codex
openspec init --tools claude,cursor
openspec init --tools all
openspec init --tools none

常见用法：

• openspec init：交互式初始化
• openspec init ./my-project：在指定目录初始化
• openspec init --tools codex,cursor：只为指定工具生成 OpenSpec 配置
• openspec init --profile core：本次初始化时显式使用 core profile

4. 默认工作流：最推荐的上手路径

OpenSpec 当前默认 profile 是 core，提供 4 个主命令：

• /opsx:propose
• /opsx:explore
• /opsx:apply
• /opsx:archive

最常用的流程就是：

/opsx:propose -> /opsx:apply -> /opsx:archive

如果需求还不明确，可以先加一个探索动作：

/opsx:explore -> /opsx:propose -> /opsx:apply -> /opsx:archive

下面按一次典型功能开发来说明。

4.1 第一步：创建变更提案

在 AI 助手的聊天窗口输入：

/opsx:propose add-dark-mode

这一步通常会完成这些事情：

• 创建 openspec/changes/add-dark-mode/
• 生成 proposal.md
• 生成 specs/
• 生成 design.md
• 生成 tasks.md

也就是说，/opsx:propose 相当于把一次变更的 planning artifacts 一次性搭好，适合需求已经相对明确的场景。

如果你现在还拿不准需求，可以先：

/opsx:explore

它更适合这些场景：

• 性能优化，不确定瓶颈在哪里
• Bug 排查，不确定根因
• 架构调整，不确定方案边界
• 用户只给了一个模糊目标

4.2 第二步：审阅 change

在真正开工前，可以先用 CLI 看一下这次 change 的内容是否合理：

openspec list
openspec show add-dark-mode
openspec validate add-dark-mode
openspec view

这些命令分别用于：

• openspec list：列出当前 change / specs
• openspec show <change>：查看某个 change 详情
• openspec validate <change>：检查格式和结构是否符合要求
• openspec view：打开交互式 dashboard

如果你想让 AI 或脚本消费结构化输出，部分命令还支持 --json。

4.3 第三步：按 tasks 实现

确认 artifacts 没问题后，在 AI 助手里执行：

/opsx:apply add-dark-mode

AI 会按照 tasks.md 中的清单逐项实现，并在完成后把任务标记为已完成。这个阶段的关键不是“自由发挥”，而是让 AI 严格围绕已经对齐好的 spec 和 tasks 执行。

4.4 第四步：归档

实现完成后，可以在 AI 助手里归档：

/opsx:archive add-dark-mode

或者在终端里归档：

openspec archive add-dark-mode --yes

归档后通常会发生两件事：

• 把这次 change 的 delta specs 合并回 openspec/specs/
• 把变更目录移动到 openspec/changes/archive/YYYY-MM-DD-add-dark-mode/

这样主规格就同步更新了，历史变更也能被保留下来。

5. 扩展工作流：适合更精细的控制

如果你想显式控制每一步的产物创建，而不是使用默认的一步式 propose，可以开启扩展工作流。

先执行：

openspec config profile
openspec update

启用后，常见命令包括：

命令	作用
/opsx:new	只创建新的 change 骨架
/opsx:continue	根据依赖关系继续生成下一个 artifact
/opsx:ff	fast-forward，一次性生成全部 planning artifacts
/opsx:verify	校验实现是否和 artifacts 一致
/opsx:sync	把 delta specs 提前合并回主规格
/opsx:bulk-archive	批量归档多个 change
/opsx:onboard	通过引导式流程熟悉 OpenSpec

官方文档里给出了几种常见模式。

5.1 快速功能开发

当需求很明确时，可以走：

/opsx:new -> /opsx:ff -> /opsx:apply -> /opsx:verify -> /opsx:archive

5.2 探索式开发

当需求不清楚或需要先调研时，可以走：

/opsx:explore -> /opsx:new -> /opsx:continue -> ... -> /opsx:apply

5.3 并行处理多个 change

OpenSpec 也支持多个 change 并行推进。一个 change 暂停时，可以切换上下文去做另一个 change，完成后再回到原来的任务。

在多个 change 都完成时，可以使用 /opsx:bulk-archive 做批量归档。文档说明它会检查多个 change 是否触碰同一份 spec，并按实际实现情况和时间顺序处理冲突。

6. 常用 CLI 命令

OpenSpec 的命令可以分成几类：

类别	命令
初始化 / 更新	init、update
浏览	list、show、view
校验	validate
生命周期	archive
工作流辅助	status、instructions、templates、schemas
配置	config
其他	feedback、completion

其中比较常用的可以直接记住这几个：

openspec init
openspec update
openspec list
openspec show <change-name>
openspec validate <change-name>
openspec archive <change-name> --yes

如果你需要看当前 workflow 还缺哪些 artifacts，可以进一步用：

openspec status
openspec instructions

7. 一个可以直接照抄的实战流程

下面是一套最小可用流程，适合第一次落地 OpenSpec。

7.1 初始化

npm install -g @fission-ai/openspec@latest
cd my-app
openspec init --tools codex

7.2 在 AI 中创建 change

/opsx:propose add-user-profile-page

7.3 在终端里检查

openspec list
openspec show add-user-profile-page
openspec validate add-user-profile-page

7.4 在 AI 中实现并归档

/opsx:apply add-user-profile-page
/opsx:archive add-user-profile-page

如果你更习惯显式控制每一步，也可以改成：

/opsx:new add-user-profile-page
/opsx:ff
/opsx:apply
/opsx:verify
/opsx:archive

8. 与 Spec Kit、Kiro 的对比

8.1 定位差异

• OpenSpec：更像一个轻量的变更管理框架，强调 current specs + change deltas + archive。它特别适合持续演进的项目，把“系统当前规格”和“本次变更规格”分开管理。
• Spec Kit：更像一套通用的 spec-driven 开发方法论与脚手架，强调 constitution -> specify -> plan -> tasks -> implement。它更关注流程模板、团队原则和生成式工作流本身。
• Kiro：更像一个带原生 spec workflow 的 AI IDE。除了 specs，它还集成了 steering、hooks、MCP、agentic coding 等能力，属于“产品化的一体式方案”。

8.2 关键区别

维度	OpenSpec	Spec Kit	Kiro
核心重心	变更规格管理	方法论与模板化流程	IDE 内一体化体验
典型流程	propose -> apply -> archive	specify -> plan -> tasks -> implement	requirements/design/tasks -> agent 执行
对“现状”的表达	强调主规格 openspec/specs/	更强调当前 feature/branch 的 specs	以内置 spec 和任务视图为主
工具耦合度	低，偏工具无关	低，偏工具无关	高，强依赖 Kiro 自身能力
适合场景	存量项目、长期迭代、多变更并行	团队想统一 AI 开发流程	想要开箱即用的 AI IDE 体验

8.3 怎么选

• 如果你最关心的是“每次变更都能落到可归档、可追踪的规格里”，OpenSpec 更合适。
• 如果你最关心的是“给团队建立一套统一的 spec-first 开发流程”，Spec Kit 会更顺手。
• 如果你想要的是“IDE 里直接带完整 spec 工作流、任务执行和 agent 能力”，Kiro 更省心。

简单说，OpenSpec 胜在变更管理清晰，Spec Kit 胜在流程方法论完整，Kiro 胜在产品体验一体化。