AI工具►工程实践

OpenSpec 完全指南：AI 时代的规范驱动开发框架

“The most loved spec framework.”
GitHub: Fission-AI/OpenSpec · 45.4k ⭐ · MIT License

目录

  1. 什么是 OpenSpec
  2. 核心价值
  3. 设计哲学
  4. 工作原理
  5. 完整工作流
  6. 技术架构分层
  7. 标准项目结构与文件说明
  8. 入门指南
  9. 实践案例
  10. 常见问题

一、什么是 OpenSpec

OpenSpec 是一个轻量级规范驱动开发框架（Spec-Driven Development Framework），旨在让人类与 AI 编码助手在写代码之前，先就「要做什么」达成一致。

它不是一个项目管理工具，不是一个文档生成器，而是一个结构化的「共识层」——在模糊的想法和混乱的代码之间，建立起清晰的行为契约。

📖 一句话定义

OpenSpec = 在 AI 写代码之前，人类和 AI 一起填写「要做什么」的规格说明，然后按规格交付。

⚡ 与传统方案的本质区别

对比维度 传统方案 OpenSpec
需求载体 口头沟通、邮件、Issue 结构化 Artifact 文件
变更追踪 Git 历史推演 Delta Spec 增量描述
AI 协作 每次都是新对话，无记忆 规格文件作为永久上下文
灵活度 瀑布式分阶段 流体式，随时可迭代

二、核心价值

2.1 对人类（开发者/产品负责人）

  • 减少返工：AI 不会跑偏，因为规格先行
  • 可追溯：每个代码变更都有对应的 proposal → specs → design → tasks 链路
  • 灵活变更：随时回头改规格，代码跟着走

2.2 对 AI（编码助手）

  • 有据可依：不再靠「猜」，规格文档就是行动指南
  • 上下文稳定：文件比聊天历史更持久
  • 边界清晰：tasks.md 的 Checkbox 是明确的完成标准

2.3 对团队

  • 多人协作：规格是共识的基础，Code Review 有据可查
  • 跨工具集成：支持 25+ AI 工具（Claude Code、Cursor、Windsurf、Cline 等）
  • 企业级扩展：从个人项目到跨仓库企业项目均可

三、设计哲学

OpenSpec 的设计哲学浓缩为五句话：

1
2
3
4
5
6
7
fluid not rigid          # 流体式，而非僵化分阶段
iterative not waterfall  # 迭代式，而非瀑布式
easy not complex         # 简洁化，而非复杂化
built for brownfield     # 支持存量项目，而不仅是新项目
not just greenfield
scalable from personal   # 从个人项目到企业级均可
projects to enterprises

3.1 Fluid Not Rigid（流体式）

传统规范框架让你经历：规划阶段 → 实现阶段 → 完成。这是一个锁死的流程。

OpenSpec 允许你以任何顺序创建产物（Artifact）：可以从 proposal 开始，也可以从 tasks 开始。依赖关系只是指引，不是限制。

3.2 Iterative Not Waterfall（迭代式）

需求会变，理解会深化。一开始看起来正确的方案，在看到代码库后可能不成立。

OpenSpec 拥抱这个现实——随时可以回去更新任何一个 Artifact，不需要「规划阶段」的完美才开始。

3.3 Easy Not Complex（简洁化）

1
2
3
4
5
6
7
8
# 安装
npm install -g @fission-ai/openspec@latest

# 初始化（几秒钟完成）
openspec init

# 开始工作
/opsx:propose your-idea

无需繁重的格式或仪式。

3.4 Brownfield-First（存量优先）

大多数软件工作不是从零开始，而是在既有系统上修改。OpenSpec 的 Delta Spec 机制使得描述「对现有行为的变更」变得自然，而不是重新描述整个系统。

3.5 Scalable（可扩展）

规模 方案
个人项目 一个人用，openspec/ 目录足够
团队协作 共享 openspec/ 目录，规格即文档
跨仓库企业 OpenSpec Workspace 支持跨多个仓库的协调规划

四、工作原理

4.1 核心概念

OpenSpec 有三个核心概念：

  1. Specs（规格）：系统的行为真相源（Source of Truth），描述「系统现在是如何运作的」
  2. Changes（变更）：提议的修改，每个变更有独立文件夹，包含完整的规划产物
  3. Delta Specs（增量规格）：描述相对于现有规格的「增/改/删」，而非重写整个规格

4.2 Artifact 体系

每个 Change 文件夹中包含四类 Artifact，它们之间有依赖关系但不是严格阶段门：

Artifact 作用 类比
proposal.md Why & What — 动机、范围、思路 战略层
specs/ Requirements — ADDED/MODIFIED/REMOVED 需求 需求层
design.md How — 技术方案、架构决策 设计层
tasks.md Checklist — 可执行的任务清单 执行层 
1
2
3
4
proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            update as you learn

4.3 Delta Spec 的格式

这是 OpenSpec 最核心的创新。每个 Change 的 specs/ 目录不写完整的规格，而是写增量：

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

## ADDED Requirements

### Requirement: Two-Factor Authentication
系统必须在登录时要求第二个认证因子。

#### Scenario: OTP required
- GIVEN 已启用2FA的用户
- WHEN 用户提交有效凭证
- THEN 展示 OTP 挑战

## MODIFIED Requirements

### Requirement: Session Timeout
会话在30分钟不活动后失效。（原为60分钟）

## REMOVED Requirements

### Requirement: Remember Me
（已被2FA替代，已废弃）

当 Change 被 Archive 时：

  • ADDED → 追加到主规格
  • MODIFIED → 替换现有版本
  • REMOVED → 从主规格中删除

这样主规格始终是「当前系统行为」的完整描述，而 Change 只是「我想改什么」。

4.4 斜杠命令体系

OpenSpec 通过 AI 助手的斜杠命令（Slash Commands）来驱动：

命令 作用
/opsx:propose 一键创建完整变更（含所有 Artifact）
/opsx:explore 探索性研究，不创建产物
/opsx:apply 按 tasks.md 执行实现
/opsx:sync 将 Delta Spec 合并到主规格
/opsx:archive 归档完成的变更
/opsx:new 创建空变更骨架（Expanded 模式）
/opsx:continue 按依赖链创建下一个 Artifact（Expanded 模式）
/opsx:ff 快速创建所有 Artifact（Expanded 模式）
/opsx:verify 验证实现是否符合规格（Expanded 模式）

五、完整工作流

5.1 默认快速路径（Core Profile）

新安装默认启用 core profile，命令最简：

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

Step-by-Step 示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
你: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

你: /opsx:apply

AI:  Implementing tasks...
     ✓ 1.1 Add theme context provider
     ✓ 1.2 Create toggle component
     ✓ 2.1 Add CSS variables
     ✓ 2.2 Wire up localStorage
     All tasks complete!

你: /opsx:archive

AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
     Specs updated. Ready for the next feature.

5.2 扩展工作流（Expanded Profile）

启用方式：

1
2
openspec config profile   # 选择 workflows
openspec update           # 更新 AI 指令

扩展模式命令：

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

适合场景：

  • 复杂功能需要逐步审视每个 Artifact
  • 需要在 Artifact 之间迭代调整

5.3 探索式工作流

1
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

适合需求不明确时先研究，再转正式变更。

5.4 并行变更工作流

可以同时推进多个 Change：

1
2
3
4
5
Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply（在推进中）
                                        │
                                   切换上下文
                                        │
Change B: /opsx:new ──► /opsx:ff ──► /opsx:apply

完成后可用 /opsx:bulk-archive 批量归档。

六、技术架构分层

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
┌─────────────────────────────────────────────────────┐
│                 AI Coding Assistant                 │
│         (Claude Code, Cursor, Windsurf, etc.)     │
│                                                     │
│   ┌─────────────────────────────────────────────┐   │
│   │         OPSX Slash Command Layer            │   │
│   │  /propose /apply /archive /verify /sync    │   │
│   └─────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────┘
                       │ Slash Commands
┌──────────────────────▼──────────────────────────────┐
│              OpenSpec CLI (Node.js)                 │
│                                                      │
│  ┌──────────┐  ┌───────────┐  ┌───────────────┐    │
│  │   Init   │  │  Config   │  │   Artifact    │    │
│  │  Engine  │  │  Manager  │  │   Generator   │    │
│  └──────────┘  └───────────┘  └───────────────┘    │
│                                                      │
│  ┌──────────┐  ┌───────────┐  ┌───────────────┐    │
│  │  Delta   │  │   Sync    │  │   Workspace   │    │
│  │   Merge  │  │  Engine   │  │    Manager    │    │
│  └──────────┘  └───────────┘  └───────────────┘    │
└──────────────────────┬──────────────────────────────┘
                       │ File System I/O
┌──────────────────────▼──────────────────────────────┐
│                 Project Files                        │
│                                                      │
│  ┌─────────────────┐       ┌─────────────────────┐ │
│  │   openspec/     │       │   Your Source Code  │ │
│  │   ├── specs/    │       │       (任意项目)      │ │
│  │   ├── changes/  │       └─────────────────────┘ │
│  │   └── config.yaml      │                        │
│  └─────────────────┘       │                        │
│                    Delta Specs ──► Merge ──► Specs   │
└─────────────────────────────────────────────────────┘

6.1 CLI 层（Node.js）

  • 全局安装：npm install -g @fission-ai/openspec@latest
  • 依赖：Node.js >= 20.19.0
  • 包管理：支持 npm、pnpm、yarn、bun、Nix

6.2 Schema 层

OpenSpec 的工作流由 Schema 驱动。默认 Schema 是 spec-driven，定义了 Artifact 的依赖图和生成顺序。

用户可以自定义 Schema 来创建自己的 Artifact 序列。社区 Schema 发布在独立的仓库中。

6.3 AI 集成层

AI 助手通过 AGENTS.md（由 openspec init 生成）中的指令来理解 OpenSpec 命令。运行 openspec update 会重新生成这些指令以保持同步。

6.4 Workspace 层（企业/跨仓库）

1
2
3
4
5
workspace-folder/
├── changes/                          # 跨仓库协调规划
└── .openspec-workspace/
    ├── workspace.yaml   # 共享标识 + 链接名（可移植）
    └── local.yaml       # 本机路径映射（不含于共享状态）

支持的命令：

1
2
3
4
openspec workspace setup
openspec workspace list
openspec workspace link <name> <path>
openspec workspace doctor

七、标准项目结构与文件说明

7.1 初始化后的项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
project-root/
├── openspec/
│   ├── specs/                    # ⭐ 系统行为真相源
│   │   └── <domain>/
│   │       └── spec.md
│   ├── changes/                 # 提议的变更
│   │   └── <change-name>/
│   │       ├── proposal.md
│   │       ├── design.md
│   │       ├── tasks.md
│   │       └── specs/           # Delta Specs
│   │           └── <domain>/
│   │               └── spec.md
│   └── config.yaml              # 项目配置（可选）
└── src/                         # 你的源代码

7.2 各文件详解

openspec/specs/<domain>/spec.md — 系统当前行为的真相源文档

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

## Purpose
[这个领域做什么]

## Requirements

### Requirement: <名称>
[需求描述]

#### Scenario: <场景名>
- GIVEN <前置条件>
- WHEN <触发事件>
- THEN <预期结果>

openspec/changes/<change-name>/proposal.md — 「为什么做」和「做什么」

1
2
3
4
5
6
7
8
9
10
11
# Proposal: <变更名称>

## Intent
[为什么要做这个变更]

## Scope
- [包含的范围]
- [不包括的范围]

## Approach
[大致的技术思路]

openspec/changes/<change-name>/specs/<domain>/spec.md — Delta Spec，只描述增量变化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Delta for <Domain>

## ADDED Requirements
### Requirement: <新需求>
[描述]

## MODIFIED Requirements
### Requirement: <已有需求>
[新描述]
（原内容）

## REMOVED Requirements
### Requirement: <要删除的需求>
（[原因]）

openspec/changes/<change-name>/tasks.md — 实现检查清单，Checkbox 格式

1
2
3
4
5
# Tasks

## <分组>
- [ ] <任务ID> <描述>
- [x] <已完成任务>

八、入门指南

8.1 安装

前置条件：Node.js >= 20.19.0

1
2
3
4
5
# 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

也支持 pnpm、yarn、bun 和 Nix。

8.2 初始化项目

1
2
cd your-project
openspec init

这会在项目根目录创建 openspec/ 目录和 AGENTS.md 文件。

8.3 开始你的第一个变更

方式一：快速路径（推荐新手）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
你: /opsx:propose add-user-authentication

AI:  Created openspec/changes/add-user-authentication/
     ✓ proposal.md
     ✓ specs/auth/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

你: /opsx:apply

AI:  Working through tasks...
     [AI 开始实现，检查每个 checkbox]

你: /opsx:archive

方式二：扩展工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
你: /opsx:new add-user-authentication

AI:  Created openspec/changes/add-user-authentication/
     Schema: spec-driven
     Ready to create: proposal

你: /opsx:continue    # 逐步创建每个 Artifact

AI:  Artifact status:
     ✓ proposal (done)
     ◆ specs (ready)
     ◆ design (ready)
     ○ tasks (blocked - needs: specs)

你: /opsx:ff           # 快速创建剩余 Artifact

8.4 日常维护命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 查看活跃变更列表
openspec list

# 查看变更详情
openspec show <change-name>

# 验证规格格式
openspec validate <change-name>

# 交互式仪表板
openspec view

# 更新 AI 指令（每次 OpenSpec 升级后）
openspec update

8.5 启用扩展命令

1
2
3
openspec config profile
# 选择 "workflows"
openspec update

九、实践案例：电商网站的 Dark Mode 功能

Step 1：提出变更

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

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 动机、范围
     ✓ specs/ui/spec.md — 需求和场景
     ✓ design.md — 技术方案
     ✓ tasks.md — 实现检查清单

Step 2：检查生成的产物

proposal.md：

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

## Intent
用户请求深色模式选项，以减少夜间使用的眼睛疲劳。

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

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

specs/ui/spec.md（Delta）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
系统应允许用户在浅色和深色主题之间选择。

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

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

tasks.md：

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

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

Step 3：实施

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
你: /opsx:apply

AI:  Implementing add-dark-mode...

     Reading tasks.md...
     - [ ] 1.1 Create ThemeContext
     - [ ] 1.2 Add CSS custom properties
     ...

     Working on 1.1: Create ThemeContext...
     [创建 src/context/ThemeContext.tsx]
     ✓ 1.1 ThemeContext created

     Working on 1.2: Add CSS custom properties...
     [更新 src/styles/globals.css]
     ✓ 1.2 CSS custom properties added
     ...

Step 4：归档

1
2
3
4
5
6
你: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged ADDED requirements into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done!

十、常见问题

Q1：OpenSpec 和传统 PRD/Spec 文档有什么区别？

维度 传统文档 OpenSpec
用途 给人看 给人和 AI 看
变更管理 重写或版本对照 Delta Spec（增量描述）
与代码关联 分离 归档时自动合并到 specs/
AI 可执行性 低 高（tasks.md 是可执行检查清单）

Q2：我已经有了现有代码库，OpenSpec 怎么用？

Brownfield 是 OpenSpec 的首要场景。

  1. 先创建 openspec init
  2. 用 /opsx:propose <improvement> 开始描述你想改什么
  3. Delta Spec 机制让你只需要描述「改了什么」，不需要重写整个系统规格
  4. 归档时，增量自动合并到 specs/

Q3：OpenSpec 支持哪些 AI 工具？

截至目前支持 25+ AI 编码助手，包括但不限于：

  • Claude Code / Claude Desktop
  • Cursor
  • Windsurf (Codeium)
  • Cline
  • GitHub Copilot
  • JetBrains AI Assistant
  • VS Code AI 插件

完整列表见：Supported Tools 文档

Q4：多个变更同时进行会发生冲突吗？

不会。每个 Change 有独立的文件夹，互不干扰。

  • 可以随时切换 Change 上下文
  • 可以并行让 AI 处理不同 Change
  • 归档时各自合并到主规格，无冲突（因为每个规格文件在同一 domain 下）

Q5：如果 AI 实现的代码和规格不一致怎么办？

使用 /opsx:verify（Expanded 模式）来验证实现是否符合规格。验证结果会指出偏差。

Q6：OpenSpec 适合什么规模的项目？

规模 方案
个人项目 Repo-local openspec/
小团队 Repo-local + 共享规格
跨多个仓库 OpenSpec Workspace

Q7：Schema 是什么？可以自定义吗？

Schema 定义了 Artifact 的序列和依赖关系。OpenSpec 默认使用 spec-driven Schema（proposal → specs → design → tasks）。

高级用户可以通过 Customization 文档 创建自定义 Schema。

Q8：如何升级 OpenSpec？

1
2
npm install -g @fission-ai/openspec@latest
openspec update    # 在每个项目中重新生成 AI 指令

Q9：OpenSpec 会收集遥测数据吗？

默认不收集任何遥测数据。详见 Telemetry 文档

Q10：我可以在非 Node.js 项目中使用 OpenSpec 吗？

可以。OpenSpec 本质上是一套约定和文件结构，与语言/框架无关。它通过 CLI 和 AI 斜杠命令工作，不需要项目使用 Node.js。

参考链接

资源 链接
官网 https://openspec.dev/
GitHub https://github.com/Fission-AI/OpenSpec
Discord 社区 https://discord.gg/YctCnvvshC
入门文档 Getting Started
工作流 Workflows
命令参考 Commands
概念说明 Concepts
CLI 参考 CLI Reference

本文基于 OpenSpec 最新版本整理，所有信息来源于 GitHub 官方仓库。