OpenSpec

本文参考 OpenSpec GitHub 和 OpenSpec 中文文档，对 OpenSpec 规范驱动开发系统做一个汇总笔记

[TOC]

一、概述

OpenSpec 是由 Fission AI 开源的 AI-Native 规范驱动开发系统（Spec-Driven Development, SDD），为 AI 编码助手提供轻量级规范层。

核心理念：在第一行代码编写之前，先与 AI 对齐需求，让开发过程更可预测、更高效。

设计哲学：

• 流动而非僵化 — 随时更新任意产物，无需遵守僵化的阶段门控
• 迭代而非瀑布 — 按自己的节奏推进，随时可以回退修改
• 简单而非复杂 — 轻量级 Markdown + Git，不依赖额外环境
• 存量项目优先 — 通过 Delta Spec 原生支持棕地项目
• 从个人项目扩展到企业级 — 灵活适配各种规模

基本信息：

• 许可证：MIT
• 运行环境：Node.js 20+
• 支持 30+ AI 编码助手（Claude Code、Cursor、Windsurf、GitHub Copilot 等）
• 主要语言：TypeScript

二、为什么选择 OpenSpec？

AI 编码助手功能强大，但当需求只存在于聊天记录中时，结果往往难以预测。

与同类产品对比

三、安装与初始化

3.1 安装

1
2
3
4
5
6
7
8
# 全局安装（支持 npm/pnpm/yarn/bun/nix）
npm install -g @fission-ai/openspec@latest

# 进入项目目录
cd your-project

# 初始化
openspec init

3.2 初始化选项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 交互式初始化
openspec init

# 指定目录
openspec init ./my-project

# 非交互式：配置 Claude 和 Cursor
openspec init --tools claude,cursor

# 为所有支持的工具配置
openspec init --tools all

# 指定 profile
openspec init --profile core

3.3 初始化后的目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
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         # 项目配置（可选）

两个核心目录：

• specs/ — Source of Truth，按领域组织（如 specs/auth/、specs/payments/），描述系统当前行为
• changes/ — 提案目录，每个变更独立文件夹，完成后其 specs 合并到主 specs/ 目录

四、核心工作流

4.1 默认流程（core profile）

1
/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive

4.2 扩展流程（expanded profile）

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

4.3 三步完成一个完整变更

Step 1：Propose — 描述变更

1
2
3
4
5
6
7
8
You: /opsx:propose add-dark-mode

AI:  已创建 openspec/changes/add-dark-mode/
✓ proposal.md — 为什么做、做什么
✓ specs/       — 需求与验收场景
✓ design.md    — 技术实现方案
✓ tasks.md     — 实现任务清单
准备开始实现！

Step 2：Apply — 按规范实现

1
2
3
4
5
6
7
8
You: /opsx:apply

AI:  正在实现各项任务...
✓ 1.1 创建主题上下文 Provider
✓ 1.2 创建主题切换组件
✓ 2.1 添加 CSS 变量
✓ 2.2 接入 localStorage
所有任务完成！

AI 按照 tasks.md 逐项执行，不会偏离。如果中断，下次会从中断处继续。

Step 3：Archive — 归档完成

1
2
3
4
You: /opsx:archive

AI:  已归档至 openspec/changes/archive/2026-03-10-add-dark-mode/
✓ 规范已更新。准备好下一个功能！

归档做两件事：

1. 将 Delta Specs 合并到 openspec/specs/（更新 source of truth）
2. 将变更文件夹移动到 openspec/changes/archive/<日期>-<change-name>/

五、四大产物（Artifacts）

每个变更文件夹包含四个产物，层层递进：

1
2
3
4
proposal ──► specs ──► design ──► tasks ──► implement
▲           ▲          ▲                    │
└───────────┴──────────┴────────────────────┘
              随时可回溯更新

示例：proposal.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

示例：tasks.md

1
2
3
4
5
6
7
8
9
10
11
# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

六、Delta Spec（核心概念）

6.1 什么是 Delta Spec？

Delta Spec 是 OpenSpec 最重要的概念。简单来说：

Delta Spec = 行为变更的 diff

它不是重写整份规范，而是只描述”相对于当前系统，哪些行为发生了变化”。

类比理解：

• Git 的 diff 描述的是代码文件的变化
• Delta Spec 描述的是系统行为/需求的变化

为什么不直接改主 spec？因为在实际开发中，可能同时有多个功能并行开发（比如 A 在做认证改造，B 在做支付优化），如果都直接修改主 spec 文件，就会产生冲突。Delta Spec 让每个变更独立描述自己的改动，互不干扰，最终归档时才合并。

6.2 Delta Spec 在产物中的体现

当你执行 /opsx:propose add-2fa 后，AI 会生成如下结构：

1
2
3
4
5
6
7
openspec/changes/add-2fa/
├── proposal.md           # 为什么做（动机、范围）
├── specs/                # Delta Spec 就在这里！
│   └── auth/
│       └── spec.md       # ← 这就是 Delta Spec 文件
├── design.md             # 怎么做（技术方案）
└── tasks.md              # 做什么（任务清单）

注意 specs/ 文件夹——它不是完整的系统规范，而是只包含本次变更涉及的行为差异。

同时，项目中还有主规范：

1
openspec/specs/auth/spec.md    ← 主 spec（当前系统的完整行为描述）

关系图：

1
2
3
4
5
6
主 spec（当前状态）          Delta Spec（变更描述）
┌─────────────────┐       ┌──────────────────────┐
│ openspec/specs/ │       │ openspec/changes/    │
│   auth/spec.md  │  ◄──  │   add-2fa/specs/     │
│   pay/spec.md   │  归档  │     auth/spec.md     │
└─────────────────┘  合并  └──────────────────────┘

6.3 Delta Spec 的格式

使用三个 section 标记变更类型：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

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

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA.)

6.4 三种变更类型及归档行为

6.5 完整生命周期示例

假设主 spec openspec/specs/auth/spec.md 当前内容为：

1
2
3
4
5
6
7
8
9
10
11
12
# Auth Specification

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

### Requirement: Session Expiration
The system MUST expire sessions after 30 minutes of inactivity.

### Requirement: Remember Me
The system MAY offer a "Remember Me" checkbox.

现在要加 2FA、改超时时间、删掉 Remember Me，AI 生成的 Delta Spec 如上面 6.3 所示。

执行 /opsx:archive 后，主 spec 变为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Auth Specification

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

### Requirement: Two-Factor Authentication          ← ADDED
The system MUST support TOTP-based two-factor authentication.

### Requirement: Session Expiration                  ← MODIFIED
The system MUST expire sessions after 15 minutes of inactivity.

                                                     ← REMOVED: Remember Me 不再存在

变更文件夹则被移动到 openspec/changes/archive/2026-05-12-add-2fa/，作为历史记录。

6.6 为什么用 Delta 而不是重写整个 Spec？

七、Spec 格式

Specs 是行为契约，不是实现细节。使用 需求 + 场景 描述：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Auth Specification

## Purpose
Authentication and session management.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT token upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard

#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued

关键点：

• 使用 Given/When/Then 描述场景，每个场景可测试
• 使用 RFC 2119 关键词（MUST/SHALL/SHOULD/MAY）表达需求强度

八、命令参考

8.1 Slash 命令（AI 助手中使用）

扩展命令（需切换 profile）：

8.2 CLI 命令（终端中使用）

8.3 不同 AI 工具的命令格式

九、Explore 模式

当你不确定要做什么时，使用探索模式：

1
2
3
4
5
6
7
8
9
10
11
12
13
You: /opsx:explore
AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?
AI:  Let me investigate your current auth setup...
I see you're using session-based auth for the web app.
For mobile, we have three options:
1. JWT tokens (stateless, works offline)
2. OAuth2 (third-party login)
3. Extend current sessions (simpler)

You: Let's go with JWT.
AI:  Ready. Run /opsx:propose add-jwt-auth to begin.

Explore 模式不产生任何产物，只用于讨论和分析。确定方向后再执行 /opsx:propose。

十、Verify 验证

1
/opsx:verify

三个维度的验证：

报告分三个级别：CRITICAL、WARNING、SUGGESTION。不阻塞归档，但提醒需要关注的地方。

十一、Schema 自定义

默认的 spec-driven schema 流程：

1
proposal → specs → design → tasks → implement

可以自定义 schema，例如增加 research 阶段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 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]

1
openspec schema init research-first

十二、适用场景与注意事项

适用场景

• 涉及多文件、多模块的功能开发
• 需要技术方案设计的变更
• 团队协作、需求追踪
• 存量项目的增量修改

不适用场景

• 改一行 CSS、修一个 typo — 直接做，无需走 propose 流程
• 极其简单的变更

使用体会

1. AI 不再跑偏 — 读了 openspec/specs/ 后，AI 已经知道项目上下文
2. proposal.md 的 scope 很有用 — 写清楚”不做什么”，AI 就不会”好心”帮你多做
3. design.md 迫使提前思考 — 很多时候设计阶段就发现方案不可行，省去了实现后再推翻的时间
4. 唯一的额外成本 — 不能直接告诉 AI “加个暗色模式”就等结果，需要先 propose、review，再 apply。但换来的是可预测性和可追溯性

十三、多语言配置

默认情况下 OpenSpec 生成的产物（proposal、specs、design、tasks）使用英文。如果希望 AI 用中文生成这些产物，可以在 openspec/config.yaml 中添加语言指令：

1
2
3
4
5
# openspec/config.yaml
schema: spec-driven

context: |
  语言：中文（简体）

配置 context 字段后，AI 在生成所有产物时都会使用中文（简体）。这个 context 字段本质上是附加给 AI 的全局提示词，你也可以写入其他项目级的上下文信息，例如：

1
2
3
4
5
context: |
  语言：中文（简体）
  项目名称：XX电商平台
  技术栈：Spring Boot + Vue 3 + MySQL
  团队约定：所有需求使用 Given/When/Then 格式

十四、总结

OpenSpec 不替代 AI 编码助手 — 它在 AI 助手前面加了一个规范层。

核心概念回顾：

• Specs — 系统行为的 Source of Truth
• Changes — 用 Delta Spec 描述修改，不重写整个 spec
• Artifacts — proposal（为什么）→ specs（变了什么）→ design（怎么做）→ tasks（做什么）
• Archive — 完成后合并 delta 到主 spec，形成系统的演进记录

参考链接：

• OpenSpec GitHub
• OpenSpec 中文文档
• OpenSpec 官网
• npm 包: @fission-ai/openspec

• Previous
  JVM再解读
• Next
  JDK版本特性总览