1. 一句话定义

OpenSpec 是 Fission-AI（YC 孵化）开源的一套轻量级规范驱动开发（SDD，Spec-Driven Development）框架。它把"规范"做成活的——每个功能改动对应一个变更文件夹，只写增量差异（ADDED / MODIFIED / REMOVED），归档后自动合并回主规范库。不像 Spec Kit 那样走严格门禁路线，OpenSpec 的核心设计理念是轻量迭代——“fluid not rigid · iterative not waterfall · easy not complex · built for brownfield not just greenfield”。

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

---

2. 适用场景

新项目和存量项目都覆盖，存量项目是真主场。

从零开始的项目能用 OpenSpec 快速建立规范遗产——propose → apply → archive 三个命令即完成一个变更闭环，简洁直接。

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

---

3. 它解决了什么问题

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

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

不像 Spec Kit 核心工作流偏向新项目，OpenSpec 从一开始就把存量项目当一等公民设计。

---

4. 核心亮点

4.1 Delta 规范模型

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

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

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

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

4.2 两目录模型

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

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

4.3 命令体系

OpenSpec 默认提供 5 个核心命令，开启扩展模式后共 11 个。命令语法因 AI 工具而异——Claude Code 用冒号（/opsx:propose），Cursor/Windsurf 用连字符（/opsx-propose），Kimi/Trae 用 skill 格式。本文统一以 Claude Code 格式为例。

核心命令（core profile，默认可用）：

命令	用途
/opsx:propose	一键创建变更文件夹并生成全部规划产物（proposal + specs + design + tasks）
/opsx:explore	探索性调研——不创建产物，用于理清需求、对比方案、分析问题
/opsx:apply	按 tasks.md 清单逐条实现代码
/opsx:sync	将 delta spec 合并到主规范库（archive 时会自动提示，通常无需手动执行）
/opsx:archive	变更完成，合并 delta spec，移入 archive 目录并保留完整审计记录

扩展命令（需 openspec config profile 开启）：

命令	用途
/opsx:new	创建变更目录骨架和 .openspec.yaml 元数据，显示首个产物模板
/opsx:continue	按依赖图逐步创建下一个产物（proposal → specs → design → tasks），适合需求模糊时
/opsx:ff	快速填充（Fast-Forward）——一次性按依赖顺序生成所有规划产物，适合需求明确时
/opsx:verify	三维验证：完整性（Completeness，全做了吗）、正确性（Correctness，做对了吗）、一致性（Coherence，代码和设计对得上吗）
/opsx:bulk-archive	批量归档多个已完成变更，自动检测跨变更 spec 冲突
/opsx:onboard	交互式入门引导——用实际代码库走一遍完整工作流，约 15-30 分钟

4.4 两种工作模式

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

如果不启用扩展模式，默认路径更简洁：propose → apply → archive，适合大部分日常改动。

依赖关系是使能（enabler）而非门禁（gate）——依赖图告诉你"可以做什么"而非"必须按什么顺序做"。设计文档（design.md）可以跳过，spec 和 design 可以并行创建。和 Spec Kit 的"不跳步"相反，OpenSpec 相信开发者知道什么时候该快、什么时候该慢。

4.5 跨 25+ AI 编程助手

支持 Claude Code、Cursor、Windsurf、GitHub Copilot、Codex、Amazon Q Developer、Auggie（Augment CLI）、Kilo Code、OpenCode、Factory Droid、Gemini CLI、RooCode、Qwen Code 等 25 个以上工具。每个工具都有对应的 skill 文件和命令适配器。

4.6 并行变更

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

---

5. 概览

项目	数据
仓库	github.com/Fission-AI/OpenSpec
Stars	53.7K+（截至 2025 年中）
分叉	3.8K+
许可证	MIT
作者	Tabish（Fission-AI，YC 孵化）
最新版本	v1.x（npm 包 @fission-ai/openspec）
依赖	Node.js 20.19.0+，支持 npm / pnpm / yarn / bun

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

---

6. 优点 & 缺点

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

---

7. 安装方式

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

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

终端执行：

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

然后进入你的项目目录：

cd my-project
openspec init

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

方式二：用其他包管理器

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

开启扩展命令（可选）

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

---

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

假设你有一个运行了一段时间的博客系统（Node.js + Express），代码量可观但没有任何规范文档。现在要加文章搜索功能。以下是 OpenSpec 的存量项目流程——不需要先补全整个系统的 spec。

以下示例以 Claude Code 的命令格式（/opsx:propose）为准。其他工具的命令格式参见 §4.3 说明。

注意：示例中的 /opsx:verify 是扩展命令，需先执行 openspec config profile 选择 expanded 模式并 openspec update（见 §7）。如果使用默认的 core 模式，跳过 Step 4 直接归档即可。

---

Step 1：初始化 OpenSpec

在终端进入项目目录：

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/
│       └── spec.md   # Delta spec（当前 specs 库为空，所以全是 ADDED）
├── design.md       # 技术方案
└── tasks.md        # 实现清单

spec.md 的内容示例：

## 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...
           - specs/search/spec.md → openspec/specs/search/spec.md (created)
           
           Archiving change...
           → openspec/changes/archive/2026-05-08-add-blog-search/

归档完成后：

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

关键：你不需要花时间给整个博客系统补全规范。 specs 库里只有一个 search/spec.md——它是在这次改动中自然长出来的。下次改认证模块，auth/spec.md 会长出来；改支付，payments/spec.md 会长出来。规范库随代码演进逐步生长。

✅ 功能上线，规范落库。

---

总结：OpenSpec 的核心洞察是——规范的敌人不是"写不出来"，而是"写不动"。全量规范的门槛让大多数存量项目望而却步。Delta 模型把这道门槛拆成了每次改动只需写几行的增量操作。改动即规范，规范随代码演进自然生长。如果你正在维护一个没有规范的存量项目，OpenSpec 是目前门槛最低的起步方式之一。