1. OpenSpec 是什么

OpenSpec 是一个开源的、轻量级 AI 辅助规格驱动开发框架。它用 Markdown 文件存规格与变更，用 Slash 命令（如 /opsx:propose、/opsx:apply）驱动 AI 助手，用 CLI 管理状态、验证格式、归档变更。

简单说，它把「聊出来的需求」变成「可追踪、可迭代、可归档的契约」——写代码前先对齐，实现中随时修正，完成后把变更沉淀为系统行为的真相来源。

支持 Cursor、Claude Code、GitHub Copilot、Codex、Windsurf 等 25+ 种 AI 编程工具。

• 项目仓库：https://github.com/Fission-AI/OpenSpec
• npm 包：https://www.npmjs.com/package/@fission-ai/openspec

2. 为什么需要它

AI 编程助手已经很强，但常见体验是：

• 对话里描述需求，AI 立刻写代码
• 实现到一半发现理解偏差，不得不大改
• 上下文被历史对话占满，关键约束被遗忘
• 多个功能并行，需求散落在聊天记录里，无法 review

根本原因是：需求只存在于聊天历史，没有结构化的「规格层」。

OpenSpec 解决的就是这个问题——在写代码之前，人和 AI 先就「要做什么」达成一致；写代码之后，把变更归档，让规格持续更新。

3. 核心设计哲学

OpenSpec 的四个原则：

传统规格系统锁死在「先规划、再实现、然后结束」的阶段里。OpenSpec 允许你在任何时刻创建、修改任意 Artifact，实现中发现设计有问题，直接改 design.md 然后继续 /opsx:apply。

大多数软件工作不是从零搭建，而是修改现有系统。OpenSpec 的 Delta Spec（增量规格） 机制，让你只描述「变了什么」，而不是重写整份规格。

4. 目录结构

OpenSpec 在项目里创建 openspec/ 目录：

openspec/
├── specs/              # 真相来源——系统当前的行为规格
│   └── <domain>/
│       └── spec.md
├── changes/            # 进行中的变更——每个功能一个文件夹
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta 规格
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

• Specs 描述系统当前如何工作
• Changes 描述系统将要如何改变

这种分离带来三个好处：多个 Change 可并行开发；Review 时 proposal、design、delta specs 一目了然；归档后 Change 移入 changes/archive/，保留完整决策上下文。

5. OPSX 工作流

OpenSpec 的标准工作流叫 OPSX（OpenSpec eXtended workflow），替代了早期的 Legacy 工作流（/openspec:proposal 等）。

Artifact 依赖关系：

proposal（根节点）
    ├── specs（requires: proposal）
    └── design（requires: proposal）
            └── tasks（requires: specs, design）

specs 和 design 可以并行创建；tasks 需要两者完成后才能创建——但不需要技术设计时可以跳过 design。

5.1 两种使用模式

默认快捷路径（core profile）：

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

一条命令创建所有规划 Artifacts，适合大多数场景。

扩展工作流：

1
2

openspec config profile   # 选择 expanded 工作流
openspec update             # 刷新 AI 指令

/opsx:new → /opsx:ff 或 /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive

• /opsx:new — 只创建 Change 脚手架
• /opsx:continue — 逐个创建 Artifact
• /opsx:ff — 快进，一次性创建所有规划 Artifacts
• /opsx:verify — 验证实现是否符合规格

6. 快速上手

6.1 环境要求

• Node.js 20.19.0 或更高版本
• 任意支持的 AI 编程工具（Cursor、Claude Code 等）

6.2 安装与初始化

1
2
3
4
5
6
7

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

cd your-project
openspec init

# 只配置特定工具
openspec init --tools cursor,claude

初始化后会生成 openspec/ 目录，以及 AI 工具的 Skills 和 Commands 文件（如 .cursor/skills/、.cursor/commands/）。

6.3 第一个 Change

在 AI 对话中：

/opsx:propose add-user-profile-page

AI 会创建 openspec/changes/add-user-profile-page/，生成 proposal、specs、design、tasks 四个 Artifact。

然后依次执行：

/opsx:apply      # 按 tasks.md 逐项实现
/opsx:archive    # Delta Specs 合并入主 Specs，Change 移入 archive

7. 实战示例：添加深色模式

7.1 提议变更

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做、改什么
     ✓ specs/       — 需求与场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单

proposal.md 回答意图、范围、方案：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Proposal: Add Dark Mode

## Intent
用户反馈需要深色模式，减少夜间使用的视觉疲劳。

## Scope
- 设置页添加主题切换
- 支持系统偏好检测
- 偏好持久化到 localStorage

Out of scope:
- 自定义配色主题（后续迭代）

## Approach
使用 CSS 自定义属性做主题，React Context 管理状态。

specs/ui/spec.md 是 Delta 规格：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

tasks.md 是实现清单：

1
2
3
4
5
6
7
8

## 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

7.2 实现与归档

You: /opsx:apply
AI:  Working through tasks... All tasks complete!

You: /opsx:archive
AI:  ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/

实现过程中如果发现设计需要调整——比如改用 Tailwind 的 dark: 前缀——直接编辑 design.md，然后继续 /opsx:apply。这就是 OPSX「流体动作」的核心价值。

8. Delta Spec

Delta Spec 是 OpenSpec 最关键的概念，也是「brownfield-first」哲学的技术体现。它用三个章节描述变更类型：

1
2
3
4
5
6
7
8

## ADDED Requirements
（新增的行为——归档时追加到主 Spec）

## MODIFIED Requirements
（修改的行为——归档时替换原有 Requirement）

## REMOVED Requirements
（废弃的行为——归档时从主 Spec 删除）

归档时，Change 里的 Delta Spec 合并入主 Spec，完整 Change 上下文保留在 changes/archive/。

9. Artifact 说明

每个 Change 包含四类 Artifact：

proposal → specs → design → tasks → implement
   │          │         │         │
  为什么      改什么     怎么做     具体步骤
 + 范围     (Delta)   (技术决策)  (Checkbox 清单)
 + 方案

9.1 Proposal — 意图与范围

回答：Intent（解决什么问题）、Scope（什么在范围内/外）、Approach（大致怎么解决）。

9.2 Specs — 行为契约

Spec 描述可观察的行为，不是实现细节。

应该写进 Spec 的：用户或下游系统依赖的可观察行为、输入输出错误条件、安全/隐私/可靠性约束、可测试的场景（Given/When/Then）。

不应该写进 Spec 的：内部类名/函数名、库或框架选型、逐步实现计划（这些属于 design.md 或 tasks.md）。

快速判断：实现方式变了但外部可见行为不变，就不属于 Spec。

9.3 Design — 技术方案

记录架构决策、数据流、文件变更计划，ADR 风格：

1
2
3
4
5

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

9.4 Tasks — 实现清单

带 checkbox 的具体步骤，按层级编号（1.1、1.2、2.1…），每组任务控制在一次会话可完成的粒度。

10. Slash 命令速查

何时更新现有 Change vs 创建新 Change

原则：更新保留上下文，新建提供清晰度——同一功能持续 commit， genuinely 新功能开新分支。

11. CLI 常用命令

1
2
3
4
5
6
7
8
9

openspec list                              # 查看进行中的 Changes
openspec show add-dark-mode                # 查看 Change 详情
openspec validate add-dark-mode            # 验证 Spec 格式
openspec status --change add-dark-mode --json  # JSON 状态（供 AI 查询）
openspec view                              # 交互式 Dashboard
openspec schemas                           # 列出可用 Schema
openspec schema init my-workflow           # 创建自定义 Schema
openspec schema fork spec-driven my-workflow
openspec update                            # 升级后刷新 AI 指令

升级 OpenSpec：

1
2

npm install -g @fission-ai/openspec@latest
cd your-project && openspec update

12. 与同类方案对比

12.1 vs. GitHub Spec Kit

Spec Kit 功能全面但较重：严格阶段门禁、大量 Markdown 模板、需要 Python 环境。OpenSpec 更轻：秒级初始化，没有阶段锁定，随时迭代。

12.2 vs. AWS Kiro

Kiro 规格能力强大，但锁定在 Kiro IDE 内、主要支持 Claude 模型。OpenSpec 更开放：支持 25+ AI 工具，用你已有的工具链。

12.3 vs. 什么都不做

没有规格层的 AI 编程：模糊需求 → 不可预测结果；上下文污染 → 关键约束被遗忘；无法 Review → 变更散落在聊天历史。OpenSpec 在可预测性和轻量之间取得平衡。

13. 自定义工作流

13.1 项目配置（config.yaml）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e  

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

• context 注入到所有 Artifact 的 AI 指令中
• rules 按 Artifact 类型注入额外规则
• Schema 优先级：CLI flag > Change 元数据 > config.yaml > 默认

13.2 自定义 Schema

默认的 proposal → specs → design → tasks 不适合你的团队时，可以创建自定义 Schema：

1
2

openspec schema init research-first
openspec schema fork spec-driven research-first

示例「先调研再提案」工作流：

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

# 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]

依赖图：research → proposal → tasks（跳过 specs 和 design）。

13.3 多仓库协作（Workspace Beta）

工作跨越多个 Repo 或 Monorepo 多个目录时，OpenSpec 提供 Workspace 能力：

1
2
3
4
5
6

openspec workspace setup
openspec workspace setup --no-interactive --name platform \
  --link /repos/api --link web=/repos/web
openspec workspace list
openspec workspace open platform --agent github-copilot
openspec workspace doctor

Workspace 是本地协调面，每个 Repo 的 openspec/ 仍是 Specs 和 Changes 的家。实现和归档仍在各自 Repo 中进行。

14. 使用建议

14.1 模型与上下文

OpenSpec 在高推理能力模型上效果最好（如 Codex 5.5、Opus 4.7 等）。开始实现前清空上下文窗口——Artifact 文件本身就是结构化上下文，不需要把全部聊天历史塞进窗口。

14.2 规格严格度

OpenSpec 反对过度文档化，根据风险选择深度：

Lite Spec（默认，大多数 Change）： 简短的行为优先需求、清晰范围和非目标、几个验收检查。

Full Spec（高风险 Change）： 跨团队/跨 Repo 变更、API/合约变更、迁移、安全/隐私相关、歧义可能导致昂贵返工的场景。

14.3 工作流选择

15. 常见问题

Q: OpenSpec 会增加多少文档负担？

A: 目标是「最小必要规格」。大多数 Change 用 Lite Spec 即可——几个 Requirement + Scenario，加上 tasks 清单。AI 会帮你生成初稿，你只需要 review 和修正。

Q: 必须用 OpenSpec 才能用 AI 编程吗？

A: 不是。OpenSpec 是可选的结构化层。但如果你经历过「AI 理解偏差导致返工」的痛苦，这层结构的投资回报率很高。

Q: 现有项目怎么接入？

A: 直接在现有项目根目录运行 openspec init，不需要重构代码。先从下一个新功能开始用，逐步积累 Specs。

Q: Spec 和测试是什么关系？

A: Spec 中的 Scenario 应该是可测试的——你可以（也应该）为 Scenario 写自动化测试。Spec 是行为契约，测试是契约的验证。

Q: 支持哪些 AI 工具？

A: 25+ 工具，包括 Cursor、Claude Code、GitHub Copilot、Codex、Windsurf、Cline、Gemini CLI、Amazon Q 等。完整列表见 Supported Tools 文档。

16. 小结

OpenSpec 的核心价值：在 AI 写代码之前先对齐，写代码之后把变更沉淀为系统规格。

完整工作循环：

1. Specs 描述当前行为
2. Changes 提议修改（Delta Specs）
3. /opsx:apply 实现变更
4. /opsx:archive 合并 Delta，更新 Specs
5. Specs 描述新行为
6. 下一个 Change 基于更新后的 Specs 继续

如果你正在用 AI 编程助手做严肃的项目开发，OpenSpec 值得一试。初始化只需几秒钟，第一个 Change 从 /opsx:propose 开始。