OpenSpec 入门：用规格文档管住 AI 协作框架的边界感

入门级 | 约 15 分钟 | 你将掌握 OpenSpec 的核心概念（Delta Specs、Artifact 依赖图）、初始化流程、OPSX 工作流（propose → apply → archive）、以及多变更并行管理

---

项目简介

我们先来承认一个事实：你用 AI 编程助手的时候，有没有遇到这种情况——聊着聊着，AI 把原本不想改的地方也改了；或者换了对话上下文，AI 完全忘了之前说了什么；或者每次让 AI 写新功能，做出来的东西和你想要的根本不是一回事。

这些问题不是 AI 太笨，而是需求从来没有被「签字画押」过。它只存在于聊天记录里，AI 自由发挥的空间太大了。

OpenSpec 做的事情很简单：在动手写代码之前，先让人和 AI 对齐一份规格文档，然后 AI 按这份文档来行动。它由 Fission-AI 开发，支持 20+ AI 编程工具（Claude Code、Cursor、Windsurf 等），本质上是给 AI 编程助手加了一个轻量级的规格管理层。

---

目标读者画像

• 日常使用 AI 编程助手的开发者
• 团队协作中苦于人和 AI 需求理解不一致的工程师
• 想让 AI 产出更可控的产品经理

核心依赖与环境

• Node.js 20.19.0+

完整项目结构树

openspec/
├── specs/                    # 系统当前行为规格（按域划分）
│   └── <domain>/spec.md
├── changes/                  # 变更提案（每变更一个文件夹）
│   ├── <change-name>/
│   │   ├── proposal.md       # 动机 + 范围 + 方案
│   │   ├── specs/             # Delta 规格（ADDED/MODIFIED/REMOVED）
│   │   │   └── <domain>/spec.md
│   │   ├── design.md         # 技术设计
│   │   └── tasks.md          # 实现检查清单
│   └── archive/               # 归档历史
└── config.yaml               # 项目配置（可选）

---

手把手步骤

第 1 步：全局安装 OpenSpec

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

安装完成后验证一下：

openspec --version
# 1.2.0

第 2 步：初始化项目

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

cd your-project
openspec init

这个命令会做三件事：

1. 创建 openspec/ 目录结构
2. 生成 .claude/ 下的 AI 技能文件（让 AI 助手能识别 /opsx:* 命令）
3. 询问你是否创建项目配置文件 config.yaml（可选，用于注入项目上下文）

初始化完成后，你的项目多了这些目录：

openspec/
├── specs/       # 当前系统行为规格（空目录，等待填充）
├── changes/     # 变更提案目录（空目录）
└── config.yaml  # 项目配置（如果选择了创建）

第 3 步：启用 OPSX 扩展工作流

新安装的 OpenSpec 默认是 core 模式，只有 4 个命令：propose、explore、apply、archive。如果你想用完整的工作流（包括 new、continue、ff、verify、bulk-archive 等），执行：

openspec config profile
# 选择 expanded 或 full
openspec update

openspec update 会根据你选择的 profile 重新生成 AI 技能文件，让你和 AI 的对话中可以使用更多命令。

第 4 步：创建第一个变更——加暗色模式

现在让 AI 帮你创建一个变更。我们以「给应用加暗色模式」为例，直接告诉 AI：

/opsx:propose add-dark-mode

AI 会自动在 openspec/changes/add-dark-mode/ 下创建四个 Artifact 文件：

openspec/changes/add-dark-mode/
├── proposal.md     # 这个变更是为了什么？范围？方案？
├── specs/
│   └── ui/spec.md  # UI 域的 Delta 规格
├── design.md       # 技术方案怎么设计？
└── tasks.md        # 具体要做什么？一步步列出来

proposal.md 长这样（AI 自动生成，你和 AI 可以一起改）：

# Proposal: Add Dark Mode

## Intent
用户请求添加暗色模式，减少夜间使用的眼睛疲劳。

## Scope
- 在设置中添加主题切换按钮
- 支持系统偏好检测
- 将偏好持久化到 localStorage

## Approach
使用 CSS 变量做主题，用 React Context 管理状态。

specs/ui/spec.md 是关键的 Delta 规格，格式如下：

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
系统 SHALL 允许用户在浅色和暗色主题之间切换。

#### Scenario: Manual toggle
- GIVEN 用户在任意页面
- WHEN 用户点击主题切换按钮
- THEN 主题立即切换，且偏好跨会话持久化

#### Scenario: System preference
- GIVEN 用户没有保存的偏好
- WHEN 应用加载
- THEN 使用系统首选颜色方案

tasks.md 是实现检查清单：

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 创建 ThemeContext（light/dark 状态）
- [ ] 1.2 添加 CSS 变量定义颜色
- [ ] 1.3 实现 localStorage 持久化

## 2. UI Components
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 在设置页添加切换按钮
- [ ] 2.3 在 Header 添加快捷切换

## 3. Styling
- [ ] 3.1 定义暗色主题配色
- [ ] 3.2 让现有组件使用 CSS 变量

第 5 步：执行实现任务

规格文档确认无误后，执行实现：

/opsx:apply

AI 会逐条检查 tasks.md 中的任务，每完成一条就打一个勾。你会发现 AI 的行为变了——它不再自由发挥，而是严格按照 tasks.md 来推进。如果实现过程中发现设计有问题，可以直接修改 design.md，然后继续 apply，AI 会自动跟上。

第 6 步：验证并归档变更

验证（可选，但推荐）：

/opsx:verify

AI 会从三个维度检查你的实现：

归档：

/opsx:archive

归档会做两件事：

1. 把 Delta 规格合并到主规格 openspec/specs/ui/spec.md
2. 把变更文件夹移到 openspec/changes/archive/2026-04-11-add-dark-mode/

归档完成后，系统规格文件更新了，你多了一份完整的变更历史。

第 7 步：多变更并行管理

实际开发中，经常会中途被打断去处理其他问题。OpenSpec 支持多变更并行：

# 假设你正在做 add-dark-mode，突然要修一个 bug
/opsx:new fix-login-redirect

# 正常完成 bug 修复
/opsx:ff
/opsx:apply
/opsx:archive

# 回到之前的暗色模式工作
/opsx:apply add-dark-mode

当你有多个变更都完成后，一起归档：

/opsx:bulk-archive

OpenSpec 会自动检测规格冲突（两个变更都改了 specs/ui/），并按时间顺序合并。

第 8 步：自定义 Schema

OpenSpec 的 OPSX 工作流是基于 Schema 定义的，你可以完全自定义 Artifact 的种类和依赖关系。比如你想要一个「先研究、再提案」的工作流：

# 从默认 schema 派生一个新 schema
openspec schema fork spec-driven research-first

生成的 Schema 结构：

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

对应的依赖图变成了：

research ──► proposal ──► tasks

在 schema.yaml 中定义：

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]

  - id: tasks
    generates: tasks.md
    requires: [proposal]

第 9 步：CLI 常用命令速查

# 初始化
openspec init

# 更新 AI 技能文件（每次升级或改 profile 后都要运行）
openspec update

# 查看当前配置
openspec config show

# 切换工作流 profile
openspec config profile

# 查看活跃变更
openspec list

# 查看某个变更详情
openspec show add-dark-mode

# 验证格式
openspec validate add-dark-mode

# 交互式 Dashboard
openspec view

# Schema 管理
openspec schemas              # 列出可用 schema
openspec schema which --all   # 查看 schema 来源
openspec schema validate my-schema  # 验证 schema

---

常见问题排查

1. AI 找不到 /opsx:propose 命令

这是最常见的问题。运行 openspec init 后，AI 助手需要重新加载技能文件。执行：

openspec update

然后重新开启对话。如果 AI 依然不识别，手动检查 .claude/ 目录是否存在。

2. openspec init 报 Node.js 版本错误

node --version
# 确认 >= 20.19.0

# 如果版本太低，用 nvm 升级
nvm install 20 && nvm use 20

3. Delta 规格合并时发生冲突

/opsx:bulk-archive 时，如果两个变更修改了同一个规格文件，OpenSpec 会检测到并提示你。按时间顺序合并是默认行为，如果需要手动处理：

# 先单独归档一个
/opsx:archive fix-login-redirect

# 再归档另一个
/opsx:archive add-dark-mode

4. 自定义 Schema 加载失败

通常是因为 schema.yaml 语法错误。检查一下：

openspec schema validate my-schema

常见错误：YAML 缩进不对、artifact 的 requires 字段引用了不存在的 ID（循环依赖）。

5. AI 生成的规格格式不符合要求

可以在 openspec/config.yaml 中添加规则：

rules:
  specs:
    - 使用 GIVEN/WHEN/THEN 格式描述每个场景
    - 每个 Requirement 必须至少有一个 Scenario

这些规则会注入到 AI 生成规格的指令中。

6. /opsx:apply 过程中 AI 跳过了某些任务

直接告诉 AI：

请按 tasks.md 的顺序执行，任务 1.3 还没有完成，不要跳过。

OpenSpec 的 fluid 特性允许你随时编辑 Artifact——修改 tasks.md 后再 apply，AI 会从上次停下的地方继续。

---

扩展阅读 / 进阶方向

Delta Specs 格式深入：ADDED/MODIFIED/REMOVED 三种变更类型各有其语义——ADDED 新增需求、MODIFIED 替换已有需求、REMOVED 删除废弃需求。掌握它们的合并规则，是用好 OpenSpec 的关键。

OPSX vs Legacy 工作流对比：OpenSpec v1.x 使用的是 Legacy 工作流（/openspec:proposal），v1.2+ 主推 OPSX。两者核心区别在于：Legacy 是 phase-locked（全有或全无），OPSX 是 fluid（任意时刻可编辑任意 Artifact）。

20+ AI 工具接入指南：OpenSpec 通过 .claude/skills/ 目录生成技能文件，兼容 Claude Code、Cursor、Windsurf、Copilot 等主流工具。详见 docs/supported-tools.md。

团队 Slack 集成：企业团队可以联系 [email protected] 获取专用 Slack 频道支持，适合多人协作场景下的规格管理和审查流程。

项目配置深度定制：除了 context 和 rules，还可以通过 config.yaml 设置默认 Schema、注入项目技术栈信息（如测试框架、代码风格规范），让 AI 生成的规格更贴近你的实际项目。