Skill 学习篇（九）| 编排框架 · OpenSpec 专篇（1→10 阶段）

- [1. 一句话定义](#1. 一句话定义)
- [2. 适用场景](#2. 适用场景)
- [3. 它解决了什么问题](#3. 它解决了什么问题)
- [4. 核心亮点](#4. 核心亮点)
- - [4.1 Delta 规范模型](#4.1 Delta 规范模型)
  - [4.2 两目录模型](#4.2 两目录模型)
  - [4.3 斜杠命令工作流](#4.3 斜杠命令工作流)
  - [4.4 两种工作模式](#4.4 两种工作模式)
  - [4.5 跨 25+ AI 编程助手](#4.5 跨 25+ AI 编程助手)
  - [4.6 并行变更](#4.6 并行变更)
- [5. 概览](#5. 概览)
- [6. 优点 & 缺点](#6. 优点 & 缺点)
- [7. 安装方式](#7. 安装方式)
- - - [方式一：全局安装（推荐）（支持平台：macOS / Linux / Windows）](#方式一：全局安装（推荐）（支持平台：macOS / Linux / Windows）)
    - 方式二：用其他包管理器
    - 开启扩展命令（可选）
- [8. 实战示例：用 OpenSpec 给已有博客系统添加搜索功能](#8. 实战示例：用 OpenSpec 给已有博客系统添加搜索功能)

1. 一句话定义

OpenSpec 是 Fission-AI（YC 孵化）开源的一套轻量级规范驱动开发框架。它把"规范"做成活的------每个功能改动对应一个变更文件夹，只写增量差异（ADDED / MODIFIED / REMOVED），归档后自动合并回主规范库。不像 Spec Kit 那样 9 步严格门禁，OpenSpec 走的是"轻量迭代"路线。

和 Spec Kit 的区别：Spec Kit 是重流程、严格门禁、适合从零开始；OpenSpec 是轻量 delta、以存量项目（brownfield）为一等公民、适合在已有代码上持续迭代。

2. 适用场景

0→1 和 1→10 都覆盖，1→10 是真主场。

从零开始的项目能用 OpenSpec 快速建规范遗产------Propose → Apply → Archive 三步走，简洁直接。

但 OpenSpec 真正拉开差距的是存量项目场景（brownfield）。你不用全量补 spec------改哪个模块就给哪个模块写 delta，规范库随每次改动渐进生长。对于那些"代码跑了好几年、一行 spec 都没有"的项目，这是渐进引入规范驱动的最自然路径之一。Spec Kit 也支持存量项目（init --here），但它的全量 spec 模型在每次迭代时需要重写整个 spec 文件；OpenSpec 的 delta 模型从设计第一天就是为存量项目渐进引入规范建的------改哪写哪，不改不动。

3. 它解决了什么问题

规范驱动开发有个老问题：新项目写全套 spec 还行，已有项目怎么写？几十个接口、上百个模块，全量补 spec 根本不可行。结果就是"有规范的项目很少，没规范的项目继续裸奔"。

OpenSpec 的解法：delta 模型 。你不用一次性写整个系统的规范。每次只写你要改的那部分------用 ## ADDED 声明新增行为、## MODIFIED 声明修改行为、## REMOVED 声明删除行为。存档时自动合并进主规范库，规范随代码演进逐步生长。

不像 Spec Kit 核心工作流偏 greenfield，OpenSpec 从一开始就把 brownfield 当一等公民设计。

4. 核心亮点

4.1 Delta 规范模型

OpenSpec 的核心创新：不写全量 spec，只写增量差异。

每个变更文件夹下的 spec 文件使用三个标记：

标记	含义	归档时
`## ADDED`	新增行为	追加到主规范
`## MODIFIED`	修改已有行为	替换主规范对应条目
`## REMOVED`	删除行为	从主规范删除

这意味着你不需要一次写清楚整个系统。改 login 就写 login 的 delta，改 payment 就写 payment 的 delta。规范库是逐渐长出来的。

4.2 两目录模型

复制代码

项目根目录/
├── openspec/
│   ├── specs/           ← 主规范库，"系统当前行为的唯一真相"
│   │   ├── auth.md
│   │   └── payments.md
│   └── changes/         ← 进行中的变更
│       ├── add-dark-mode/
│       │   ├── proposal.md     # 为什么做、做什么
│       │   ├── specs/          # delta 规范（ADDED/MODIFIED/REMOVED）
│       │   ├── design.md       # 技术方案
│       │   └── tasks.md        # 实现清单
│       └── archive/            # 已完成变更归档
│           └── 2026-01-15-add-dark-mode/

两个目录的职责完全分离：specs/ 是真相来源，changes/ 是提案区。归档后 delta 合并回 specs，change 文件夹移到 archive。这套模型让"规范"从一次性文档变成了活的工程资产。

4.3 斜杠命令工作流

OpenSpec 默认提供 4 个核心命令，开启扩展模式后有 10 个：

命令	阶段	做什么
`/opsx:propose`	提案	一键创建变更文件夹（proposal + specs + design + tasks）
`/opsx:new`	建骨架	仅创建变更目录，后续手动控制
`/opsx:continue`	逐步构建	一次只创建一个产物（先 proposal，再 specs......），适合需求模糊时
`/opsx:ff`	快速填充	一次性生成所有规划产物，适合需求明确时
`/opsx:apply`	实现	按任务清单逐条实现
`/opsx:verify`	验证	三维检查：完整性（全做了吗）、正确性（做对了吗）、一致性（代码和设计对得上吗）
`/opsx:sync`	同步	将 delta spec 合并到主规范库
`/opsx:archive`	归档	变更完成，移入 archive 目录
`/opsx:bulk-archive`	批量归档	多个变更一起归档，自动检测冲突
`/opsx:onboard`	入门引导	15 分钟交互式上手

4.4 两种工作模式

Quick Feature 模式 ：new → ff → apply → verify → archive，适合需求明确的中小功能
Exploratory 模式 ：explore → new → continue（逐步构建）→ apply → archive，适合需求模糊、需要先探索代码的改动

两种模式切换自由，不强制顺序。和 Spec Kit 的"不跳步"正好相反，OpenSpec 相信开发者知道什么时候该快、什么时候该慢。

4.5 跨 25+ AI 编程助手

支持 Claude Code、Cursor、Windsurf、GitHub Copilot、Amazon Q、Codex、Gemini CLI、Kilo Code、RooCode、Qwen Code 等 25+ 个工具。每个工具都有对应的 skill 文件和 command 适配器。

4.6 并行变更

多个功能同时开发时，每个功能一个独立 change 文件夹，互不干扰。完成后用 /opsx:bulk-archive 批量归档，系统自动检测跨变更的 spec 冲突并解决。

5. 概览

项目	数据
仓库	github.com/Fission-AI/OpenSpec
Stars	46.2K+
分叉	3.2K+
许可证	MIT
作者	Tabish（Fission-AI，YC 孵化）
最新版本	v1.3.1（2026-04）
依赖	Node.js 20.19.0+，npm / pnpm / yarn / bun
日均增长	167 ⭐

OpenSpec 的定位很清晰：不是要替代 Spec Kit，而是给那些觉得 Spec Kit 太重的团队一个更轻的选择。

6. 优点 & 缺点

✅ 优点	❌ 缺点
Delta 模型，存量项目渐进引入规范	品牌认知度弱于 Spec Kit（93K vs 46K）
已达到 1.0 里程碑（v1.3.1），API 稳定	扩展命令需额外配置（`openspec config profile`）
轻量，无强制门禁，流程自由度高	自由度是把双刃剑------不自律的团队可能跳步
跨 25+ AI 编程助手	社区相对年轻，生态不如 Spec Kit 丰富
YC 孵化，势头健康	Node.js 20.19+，部分老环境需升级

7. 安装方式

OpenSpec 通过 npm 安装，也支持 pnpm、yarn、bun、nix。

方式一：全局安装（推荐）（支持平台：macOS / Linux / Windows）

终端执行：

bash 复制代码

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

然后进入你的项目目录：

bash 复制代码

cd my-project
openspec init

初始化后，项目下生成 openspec/ 目录和对应的 AI 工具 skill/command 文件。

方式二：用其他包管理器

bash 复制代码

pnpm add -g @fission-ai/openspec@latest
# 或
yarn global add @fission-ai/openspec@latest
# 或
bun add -g @fission-ai/openspec@latest

开启扩展命令（可选）

bash 复制代码

openspec config profile    # 选择 expanded 模式
openspec update            # 应用配置

8. 实战示例：用 OpenSpec 给已有博客系统添加搜索功能

假设你有一个运行了大半年的博客系统（Node.js + Express），代码一堆但一行 spec 都没有。现在要加文章搜索功能。以下是 OpenSpec 的 brownfield 流程------不需要先补全整个系统的 spec。

所有斜杠命令都在 Claude Code 聊天框中输入。

Step 1：初始化 OpenSpec

在终端进入项目目录：

bash 复制代码

cd my-blog
openspec init

首次初始化时，OpenSpec 自动检测当前项目的 AI 工具并生成对应的 skill 文件：

复制代码

OpenSpec → Detected: Claude Code
           Created: .claude/skills/openspec-core/SKILL.md
           Created: .claude/commands/opsx/propose.md
           Created: openspec/specs/          ← 空的，等待生长
           Created: openspec/changes/        ← 空的，等待第一个变更

此时 openspec/specs/ 是空的------你不需要先补全整个系统的 spec。规范从现在开始长。

✅ 环境就绪。

Step 2：提案搜索功能

在 Claude Code 聊天框输入：

复制代码

/opsx:propose 给博客系统添加文章全文搜索功能

AI 自动分析现有代码结构，然后在 openspec/changes/add-blog-search/ 下生成：

复制代码

add-blog-search/
├── proposal.md     # 为什么要做、做什么
├── specs/
│   └── search.md   # Delta spec（当前是空的 specs/ 库，所以全是 ADDED）
├── design.md       # 技术方案
└── tasks.md        # 实现清单

search.md 的内容示例：

markdown 复制代码

## ADDED Requirements
### Requirement: Full-text search for blog posts
Users can search published blog posts by keyword.
- Scenario: Search returns matching posts
  GIVEN published posts exist
  WHEN user searches for "docker"
  THEN posts containing "docker" in title or body are returned
- Scenario: Search is case-insensitive
  ...

你不需要手动写这些文件------AI 根据你的描述和现有代码自动生成。

✋ 你需要手动 review 生成的 proposal 和 tasks，确认技术方案后进入下一步。

✅ 提案通过。

Step 3：实现

在 Claude Code 聊天框输入：

复制代码

/opsx:apply

AI 自动按照 tasks.md 逐条实现：

复制代码

OpenSpec → 开始实现 add-blog-search...

[1/4] 安装全文索引库（SQLite FTS5）    ✓
[2/4] 创建搜索 API GET /api/search       ✓
[3/4] 前端搜索框组件                      ✓
[4/4] 搜索测试用例                        ✓

你不需要手动写代码------AI 根据 spec 中定义的场景和验收条件自动生成。

✅ 实现完成。

Step 4：验证

在 Claude Code 聊天框输入：

复制代码

/opsx:verify

AI 自动三维验证：

复制代码

OpenSpec → 完整性：4/4 tasks done ✓
           正确性：spec 定义的 2 个场景均已实现 ✓
           一致性：API 命名与 design.md 一致 ✓
           
           ⚠️ 建议：搜索测试未覆盖空结果场景

✋ 你需要手动确认验证结果，可选补充空结果测试。

✅ 验证通过。

Step 5：同步并归档

在 Claude Code 聊天框输入：

复制代码

/opsx:archive

AI 自动执行归档流程：

复制代码

OpenSpec → Syncing delta specs to main spec library...
           - search.md → openspec/specs/search.md (created)
           
           Archiving change...
           → openspec/changes/archive/2026-05-08-add-blog-search/

归档完成后：

复制代码

openspec/
├── specs/
│   └── search.md              ← 规范库从空开始生长了！
└── changes/
    └── archive/
        └── 2026-05-08-add-blog-search/  ← 完整变更记录存档

关键：你一分钟都没花在"给整个博客系统写 spec"上。 specs 库里只有一个 search.md------它是在这次改动中自然长出来的。下次改认证模块，auth.md 会长出来；改支付，payments.md 会长出来。规范库是活的。

✅ 功能上线，规范落库。

关键区别：OpenSpec 不强求你补全整个系统的规范。Delta 模型让规范从零开始生长------改哪写哪，不改不动。这让它成为存量项目渐进引入规范驱动的最自然路径之一。Spec Kit 也支持存量项目，但它的全量 spec 模型在每次迭代时需要重写整个 spec 文件；OpenSpec 的 delta 天生就是为渐进式规范生长设计的。