OpenSpec教程

markdown

2026年7月17日阅读约 10 分钟1,851 字

更新于 2026年7月17日

OpenSpec 完整教程：规范驱动开发（SDD）实战指南

1. 痛点导入：AI 编程的「失控」困境

1.1 AI 编程助手的能力与局限

当你使用 Claude Code、Cursor、GitHub Copilot 等 AI 编程工具时，是否遇到过以下情况？

症状	描述	后果
方向跑偏	AI 一上来就写代码，写完才发现需求理解错了	返工浪费大量时间
上下文丢失	大项目进行到一半，AI 突然「失忆」，不知道之前的设计决策	前后逻辑不一致
边界模糊	不清楚 AI 做了什么改动，为什么要这样改	代码难以维护
结果不可预测	同样的需求，不同对话给出完全不同的实现	协作困难
规范难执行	编码规范、架构决策全靠口头约定，AI 容易「跑偏」	技术债务积累

传统 AI 编程的痛点

1.2 根本原因

AI 编程助手缺乏「规格层」（Spec Layer）约束。

大多数 AI 编程工具是「问答式」的——你问，它答；你让它写，它就写。这种模式的问题在于：

需求在聊天记录里漂移：多轮对话后，原始需求可能被遗忘或曲解
没有「锁定协议」：AI 可以随时改变实现方式，无需和你确认
缺乏系统性规划：边想边写导致架构混乱，难以维护

1.3 OpenSpec 的答案

核心理念：AI 不应该一上来就写代码。它应该先退后一步，和你一起明确要构建什么，展示设计思路，编制实施计划，然后启动结构化的执行流程。

OpenSpec 为 AI 编程添加了一层「规格说明层」，让你和 AI 在写代码之前先达成共识。

2. OpenSpec 是什么？

2.1 一句话定义

OpenSpec 是一个轻量级的规范驱动开发（Spec-Driven Development, SDD）框架，专为 AI 编程助手设计。

2.2 项目档案

属性	内容
GitHub	Fission-AI/OpenSpec
Stars	58.2k
Forks	4k
最新版本	v1.5.0 (含 Stores Beta)
主要语言	TypeScript (99.2%)
许可证	MIT
支持工具	25+ 种 AI 编程助手
包管理器	npm, pnpm, yarn, bun, nix
最低要求	Node.js 20.19.0+

2.3 它不是什么？

❌ 不是	✅ 而是
替代 AI 编程工具	给 AI 编程工具装上「规范引擎」
另一个 IDE	一套轻量级的规格工作流
代码生成器	人机共识的「锁定协议」

2.4 核心价值

传统 AI 编程                    OpenSpec 赋能后
─────────────────────────────────────────────────
你问 → AI 答（随机）      →   提案 → 评审 → 共识
你让写 → AI 就写           →   规格 → 设计 → 执行
需求在聊天记录里漂移       →   需求在规范文件里锁定
结果不可预测               →   每步可追溯、可验证

3. 核心理念：规范驱动开发的五项原则

OpenSpec 的设计哲学浓缩为五项原则：

OpenSpec 五项设计原则

3.1 Fluid not Rigid（流动而非僵化）

「规范是指南，不是枷锁。」

规范文件可以随时更新，不需要经历繁琐的审批流程。当发现更好的方案时，直接修改规范，继续前进。

3.2 Iterative not Waterfall（迭代而非瀑布）

「小步快跑，持续调整。」

不要等到所有需求都完美再动手。通过快速迭代，在实践中发现和完善需求。

3.3 Easy not Complex（简单而非复杂）

「用最少的结构解决最大的问题。」

不需要为每个功能编写冗长的规格文档。OpenSpec 的最小化结构足够表达意图，又不会造成过重负担。

3.4 Built for Brownfield not Just Greenfield（支持存量项目）

「新项目能用，老项目也能用。」

OpenSpec 从第一天起就考虑了对现有项目的支持。你可以随时在既有项目中引入 OpenSpec，不需要从头重构。

3.5 Scalable from Personal Projects to Enterprises（从小到大都适用）

「一个人的项目和万人规模的企业，用的是同一套方法论。」

无论是个人 side project 还是企业级应用，OpenSpec 的核心流程保持一致，只是使用深度不同。

4. 工作流全解：四大核心命令

OpenSpec 的工作流围绕四个核心 slash 命令展开：

OpenSpec 工作流图

4.1 `/opsx:explore` —— 探索想法（Thinking Partner）

什么时候用：当你对需求还不清晰时

核心价值：作为「无风险的思考伙伴」，帮助你理清思路

工作方式：

读取你的代码库
分析现有架构
提出问题，帮你理清模糊点
评估不同方案的优劣
将模糊的想法打磨成具体的提案

输出：清晰的待解决问题列表

示例对话：

你：我想给项目加个深色模式

/opsx:explore

AI：在我深入思考之前，我想先了解几个关键问题：

1. 样式方案选择：
   - CSS 变量 + class 切换？
   - Tailwind CSS dark mode？
   - CSS-in-JS 主题系统？

2. 持久化方式：
   - localStorage？
   - 系统偏好跟随？
   - 用户手动选择？

3. 范围界定：
   - 只需适配现有组件？
   - 需要建立主题系统？
   - 考虑多主题切换？

4. 第三方库兼容：
   - 代码高亮库
   - UI 组件库
   - 图标库

请告诉我你的具体偏好，我将帮你制定详细的实施计划。

4.2 `/opsx:propose` —— 创建提案（Change Proposal）

什么时候用：需求明确后，准备开始实现前

核心价值：生成结构化的变更文档，让双方确认后再动手

创建的内容：

规范文件结构

changes/
└── your-feature/           ← 变更文件夹
    ├── proposal.md         ← 为什么要做、做什么
    ├── specs/              ← 详细规格
    │   └── spec.md
    ├── design.md           ← 怎么做、技术决策
    └── tasks.md            ← AI 可执行的任务清单

各文件职责：

文件	内容	由谁编写
`proposal.md`	变更动机、目标、范围	AI 自动生成，可修改
`specs/spec.md`	具体需求、功能点、验收标准	AI 生成 + 人工确认
`design.md`	技术方案、API 设计、数据结构	AI 生成 + 人工确认
`tasks.md`	具体的可执行任务列表	AI 生成 + 人工确认

示例：

你：/opsx:propose add-user-authentication

AI 响应：
✅ 已创建变更提案 `add-user-authentication`

📁 文件结构：
changes/add-user-authentication/
├── proposal.md      ← 变更动机与目标
├── specs/
│   └── spec.md      ← 详细功能规格
├── design.md        ← 技术设计方案
└── tasks.md         ← 实施任务清单

📋 提案摘要：
- 实现用户注册与登录
- 使用 JWT Token 认证
- 支持邮箱 + 密码登录
- 包含密码重置功能

🔍 建议：在开始实现前，请审查 proposal.md 和 design.md 确认方案。
确认后，运行 /opsx:apply 开始实施。

4.3 `/opsx:apply` —— 执行实现（Implementation）

什么时候用：提案评审通过后，准备开始编码

核心价值：按任务清单逐步执行，每步有检查点

执行模式：

tasks.md 中的任务 → 逐个执行 → 人工确认 → 继续
                              ↓
                        发现问题可暂停
                        修改规范后继续

执行过程中的检查点：

当前任务的文件路径正确
代码符合设计文档
有对应的测试覆盖
无 lint 错误

示例：

你：/opsx:apply

AI：
📋 开始执行任务 1/5

🔄 任务 1：创建用户数据模型
📁 文件：src/models/user.ts
✅ 完成

🔍 自检：
- [x] TypeScript 类型完整
- [x] 密码字段加密存储
- [ ] 需添加数据库索引

📋 任务 2/5
...

4.4 `/opsx:archive` —— 归档变更（Archive）

什么时候用：变更完成并验证通过后

核心价值：保持工作区整洁，保留变更历史

执行效果：

原位置: changes/add-user-authentication/
归档后: openspec/changes/archive/add-user-authentication/

归档内容：

完整的提案、规格、设计文档
所有任务记录
实现过程中的关键决策

保留价值：

未来可追溯「当时为什么这样设计」
新成员可快速了解项目演进历史
审计和复盘的重要依据

5. 快速入门：5 分钟安装配置

5.1 环境要求

要求	最低版本	推荐版本
Node.js	20.19.0+	最新 LTS
npm/pnpm/yarn/bun	任意版本	最新版本
Git	任意版本	最新版本

5.2 安装步骤

Step 1：全局安装 OpenSpec

# 使用 npm
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm
pnpm add -g @fission-ai/openspec@latest

# 或使用 yarn
yarn global add @fission-ai/openspec@latest

# 或使用 bun
bun add -g @fission-ai/openspec@latest

Step 2：在项目中初始化

cd your-project
openspec init

初始化会创建以下结构：

your-project/
├── openspec/               ← OpenSpec 根目录
│   ├── changes/           ← 变更文件夹
│   │   └── archive/       ← 已归档变更
│   └── specs/             ← 共享规格库（可选）
└── .openspecrc            ← 配置文件

Step 3：更新 AI 代理指令

openspec update

这会将 OpenSpec 的指令注入到 AI 代理的系统提示中，让 AI 理解并使用 OpenSpec 工作流。

Step 4：验证安装

openspec --version
# 输出: @fission-ai/openspec/1.5.0

5.3 配置你的 AI 工具

OpenSpec 支持 25+ 种 AI 编程助手。常见配置：

Claude Code：

# 更新 Agent 指令
openspec update

# 或指定配置文件
openspec update --config ./openspec.config.ts

Cursor：

打开 Cursor 设置
找到 "AI Instructions" 或 "System Prompt"
运行 openspec update 生成指令
粘贴到配置中

GitHub Copilot：

# 导出配置
openspec export --format copilot > .github/copilot-instructions.md

5.4 配置文件说明

.openspecrc 配置文件示例：

{
  "profile": "standard",
  "telemetry": true,
  "changesDir": "openspec/changes",
  "specsDir": "openspec/specs",
  "archiveDir": "openspec/changes/archive"
}

配置项说明：

配置项	默认值	说明
`profile`	`standard`	配置集，可选 `minimal`/`standard`/`extended`
`telemetry`	`true`	匿名使用统计
`changesDir`	`openspec/changes`	变更文件夹位置
`specsDir`	`openspec/specs`	共享规格库位置
`archiveDir`	`openspec/changes/archive`	归档位置

5.5 禁用遥测（可选）

# 方法一：环境变量
export OPENSPEC_TELEMETRY=0

# 方法二：
export DO_NOT_TRACK=1

6. 实战演示：完整开发流程

场景：为一个 React 项目添加「用户收藏功能」

Step 0: 准备工作

# 进入项目目录
cd my-react-app

# 初始化 OpenSpec（如果是新项目）
openspec init

# 更新 AI 代理指令
openspec update

Step 1: 探索想法（Explore）

你输入：

我想给项目添加一个「用户收藏」功能，让用户可以收藏自己喜欢的内容

AI 激活 /opsx:explore，开始提问：

🤔 在深入规划之前，我想先了解几个关键问题：

1. **收藏对象**：
   - 收藏的是帖子/文章？
   - 还是商品/商品列表？
   - 收藏项是否有数量限制？

2. **收藏夹管理**：
   - 单个收藏夹还是多个收藏夹？
   - 需要收藏夹命名/分组吗？
   - 需要分享功能吗？

3. **数据存储**：
   - 后端存储还是纯前端 localStorage？
   - 需要跨设备同步吗？

4. **交互设计**：
   - 一键收藏 vs 确认对话框？
   - 需要批量操作吗？

请告诉我你的具体需求。

你的回答：

收藏的是文章，不需要多个收藏夹，纯后端存储，需要跨设备同步

AI 继续分析并输出：

# 探索结果：用户收藏功能

## 确认的需求
- 收藏对象：文章（Article）
- 收藏夹：单一收藏夹
- 存储：后端数据库
- 同步：跨设备实时同步

## 技术考量
1. **用户-文章多对多关系**：需要关联表
2. **API 设计**：收藏/取消收藏/列表查询
3. **性能优化**：分页查询 + 索引

## 初步方案
- 创建 `user_favorites` 关联表
- 提供 RESTful API：POST/DELETE/GET /api/favorites
- 使用 JWT Token 认证用户身份

## 风险点
- 重复收藏处理
- 取消收藏的乐观更新

请确认以上理解，我将生成详细的提案文档。

Step 2: 创建提案（Propose）

你确认后，输入：

/opsx:propose user-favorites

AI 自动生成提案文件：

changes/user-favorites/proposal.md：

# 用户收藏功能提案

## 变更动机
用户需要能够收藏感兴趣的文章，方便后续查看和管理。

## 目标
- 用户可以收藏/取消收藏文章
- 用户可以查看自己的收藏列表
- 收藏数据跨设备同步

## 范围
### 包含
- 收藏/取消收藏 API
- 收藏列表查询 API
- 前端收藏按钮组件
- 收藏列表页面

### 不包含
- 收藏夹分组功能（后续迭代）
- 分享收藏夹功能（后续迭代）

changes/user-favorites/specs/spec.md：

# 用户收藏功能规格说明

## 功能点

### F1: 收藏文章
- 用户点击收藏按钮，文章被添加到收藏列表
- 重复收藏显示「已收藏」状态，不重复添加
- 返回收藏成功状态

### F2: 取消收藏
- 用户再次点击收藏按钮，取消收藏
- 返回取消成功状态

### F3: 查看收藏列表
- 显示用户收藏的所有文章
- 支持分页（每页 20 条）
- 按收藏时间倒序排列

## API 规格

### POST /api/favorites
Request:
```json
{ "articleId": "string" }

Response:

{ "success": true, "favoriteId": "string" }

DELETE /api/favorites/:articleId

Response:

{ "success": true }

GET /api/favorites?page=1&limit=20

Response:

{
  "items": [{ "articleId": "...", "title": "...", "createdAt": "..." }],
  "total": 100,
  "page": 1,
  "limit": 20
}

验收标准

用户可以成功收藏文章
用户可以取消收藏
用户可以查看收藏列表
收藏列表支持分页
重复收藏不会创建多条记录


**`changes/user-favorites/design.md`**：
```markdown
# 技术设计方案

## 数据模型

### user_favorites 表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| user_id | UUID | 用户 ID |
| article_id | UUID | 文章 ID |
| created_at | TIMESTAMP | 收藏时间 |

### 索引
- UNIQUE(user_id, article_id) — 防止重复收藏
- INDEX(user_id, created_at) — 收藏列表查询优化

## 认证
使用现有的 JWT Token 认证机制，从请求头提取用户 ID。

## 错误处理
| 场景 | 状态码 | 消息 |
|------|--------|------|
| 未登录 | 401 | Unauthorized |
| 文章不存在 | 404 | Article not found |
| 已收藏 | 200 | Already favorited |

changes/user-favorites/tasks.md：

# 实施任务清单

## 任务 1: 创建数据库迁移
- 文件：`prisma/migrations/xxx_add_user_favorites`
- 创建 user_favorites 表
- 验证：`prisma migrate status`

## 任务 2: 实现收藏 API（后端）
- 文件：`src/api/favorites.ts`
- POST /api/favorites — 收藏文章
- DELETE /api/favorites/:articleId — 取消收藏
- GET /api/favorites — 收藏列表
- 验证：API 测试通过

## 任务 3: 前端收藏按钮组件
- 文件：`src/components/FavoriteButton.tsx`
- 状态：未收藏/已收藏/加载中
- 验证：点击切换状态正确

## 任务 4: 收藏列表页面
- 文件：`src/pages/Favorites.tsx`
- 列表展示 + 分页
- 验证：页面渲染正确

## 任务 5: 集成测试
- 文件：`tests/favorites.test.ts`
- 测试收藏/取消收藏/列表查询
- 验证：所有测试通过

---
预计总时间：25-30 分钟

Step 3: 评审提案

你审查提案文件，确认方案：

提案看起来没问题，但我有一个调整：
- 分页默认改为每页 10 条，移动端更友好

你修改 specs/spec.md：

### GET /api/favorites?page=1&limit=20
修改为：
### GET /api/favorites?page=1&limit=10

Step 4: 执行实现（Apply）

你确认提案后，输入：

/opsx:apply

AI 开始执行任务：

📋 开始执行任务 1/5

🔄 任务 1：创建数据库迁移
📁 文件：prisma/migrations/xxx_add_user_favorites

✅ 完成
迁移文件已创建

🔍 自检：
- [x] 表结构正确
- [x] 索引设置正确
- [x] 迁移可执行

─────────────────────────────

📋 任务 2/5

🔄 任务 2：实现收藏 API（后端）
📁 文件：src/api/favorites.ts

✅ 完成
实现了以下端点：
- POST /api/favorites
- DELETE /api/favorites/:articleId
- GET /api/favorites

🔍 自检：
- [x] 参数验证
- [x] 错误处理
- [x] 认证检查
- [x] 重复收藏处理

─────────────────────────────

📋 任务 3/5
...

Step 5: 归档变更（Archive）

所有任务完成后，输入：

/opsx:archive

AI 响应：

✅ 变更已归档

📁 原位置：changes/user-favorites/
📁 归档位置：openspec/changes/archive/user-favorites-2026-07-02

📊 变更统计：
- 涉及文件：8 个
- 代码行数：+286 / -12
- 测试覆盖：100%

💾 归档内容：
- proposal.md
- specs/spec.md
- design.md
- tasks.md
- 实现的源代码

7. 最佳实践与避坑指南

7.1 有效使用 OpenSpec

✅ 推荐	❌ 避免
需求不清晰时先用 `/opsx:explore`	直接说「帮我写个功能」
提案评审通过后再 `/opsx:apply`	跳过评审直接实现
规范文件保持简洁	过度文档化每个细节
发现问题时更新规范再继续	绕过规范「临时凑合」
完成后及时归档	变更文件夹堆积

7.2 规范文件写作建议

proposal.md — 简洁明了

# 变更标题

## 为什么做
（1-2 句话解释动机）

## 要做什么
（核心目标，不要列具体实现细节）

## 范围
### 包含
- ...

### 不包含
- ...

specs/spec.md — 具体可测试

# 功能规格

## 功能点编号
### 功能描述
- 具体的用户故事或交互描述

## 验收标准
- [ ] 可测试的条件 1
- [ ] 可测试的条件 2

design.md — 聚焦技术决策

# 技术方案

## 决策 1
### 选项 A vs 选项 B
选择：A

理由：（为什么这个方案更好）

tasks.md — 小而可执行

## 任务 N：描述
- 文件：具体路径
- 变更：具体内容
- 验证：可执行的验证步骤

7.3 团队协作建议

提案评审是必须的：至少一人 review 提案后再开始实现
规范文件版本化：将规范文件纳入 Git 版本控制
定期归档：避免 changes/ 文件夹过于臃肿
共享规格库（Stores）：跨项目复用通用规格

7.4 模型选择建议

OpenSpec 维护者推荐以下模型用于规划和实现：

场景	推荐模型	原因
规划与设计	Codex 5.5 / Opus 4.7	高推理能力，擅长复杂决策
实现执行	Sonnet 4.6	平衡速度与质量
快速修改	Haiku 4.5	响应快，适合简单任务

7.5 常见问题解决

Q: 规范文件和代码不同步怎么办？
A: 优先更新规范文件，再同步代码。规范是「真相源」。

Q: 发现更好的方案但已经开始了？
A: 暂停实现，更新规范文档，确认后再继续。

Q: 团队成员不用 OpenSpec 怎么办？
A: 规范文件是 Markdown，任何人都可以阅读。关键是确保代码变更前有评审。

8. 与同类工具对比

8.1 工具对比表

维度	OpenSpec	Spec Kit (GitHub)	Kiro (AWS)	无规范
重量级	轻量	中等	中等	无
灵活性	高	中	低	高
IDE 依赖	无	无	有（锁定 IDE）	无
模型依赖	无	无	有	无
学习曲线	低	中	中	无
适合场景	通用	新项目为主	特定工作流	快速原型

8.2 为什么选择 OpenSpec？

vs Spec Kit：

无僵化的阶段门
支持自由迭代
随时可以修改规范

vs Kiro：

不绑定特定 IDE
不限制模型选择
兼容现有工具链

vs 无规范：

将「感觉流」变为「可预测」
建立人机共识
代码变更可追溯

8.3 资源链接

资源	链接
GitHub 仓库	https://github.com/Fission-AI/OpenSpec
官方文档	docs/ 目录下
Discord 社区	discord.gg/YctCnvvshC
问题反馈	`openspec feedback "你的反馈"`

附录

A. CLI 命令参考

命令	说明
`openspec init`	初始化 OpenSpec
`openspec update`	更新 AI 代理指令
`openspec config`	配置管理
`openspec status`	查看当前状态
`openspec archive`	归档变更
`openspec --version`	查看版本

B. 文件结构参考

project/
├── openspec/
│   ├── changes/           ← 活跃变更
│   │   └── archive/       ← 已归档变更
│   └── specs/             ← 共享规格库
├── changes/               ← 变更文件夹（由 /opsx:propose 创建）
│   └── your-feature/
│       ├── proposal.md
│       ├── specs/
│       │   └── spec.md
│       ├── design.md
│       └── tasks.md
└── .openspecrc            ← 配置文件

C. 术语表

术语	说明
Spec（规格）	需求的结构化描述
Proposal（提案）	变更的动机和目标
Design（设计）	技术方案和决策
Tasks（任务）	可执行的任务清单
Archive（归档）	将完成的变更移到历史记录

教程版本：v1.0
最后更新：2026-07-02
参考来源：Fission-AI/OpenSpec

OpenSpec 完整教程：规范驱动开发（SDD）实战指南

目录

1. 痛点导入：AI 编程的「失控」困境

1.1 AI 编程助手的能力与局限

1.2 根本原因

1.3 OpenSpec 的答案

2. OpenSpec 是什么？

2.1 一句话定义

2.2 项目档案

2.3 它不是什么？

2.4 核心价值

3. 核心理念：规范驱动开发的五项原则

3.1 Fluid not Rigid（流动而非僵化）

3.2 Iterative not Waterfall（迭代而非瀑布）

3.3 Easy not Complex（简单而非复杂）

3.4 Built for Brownfield not Just Greenfield（支持存量项目）

3.5 Scalable from Personal Projects to Enterprises（从小到大都适用）

4. 工作流全解：四大核心命令

4.1 /opsx:explore —— 探索想法（Thinking Partner）

4.2 /opsx:propose —— 创建提案（Change Proposal）

4.3 /opsx:apply —— 执行实现（Implementation）

4.4 /opsx:archive —— 归档变更（Archive）

5. 快速入门：5 分钟安装配置

5.1 环境要求

5.2 安装步骤

5.3 配置你的 AI 工具

5.4 配置文件说明

5.5 禁用遥测（可选）

6. 实战演示：完整开发流程

场景：为一个 React 项目添加「用户收藏功能」

Step 0: 准备工作

Step 1: 探索想法（Explore）

Step 2: 创建提案（Propose）

DELETE /api/favorites/:articleId

GET /api/favorites?page=1&limit=20

验收标准

Step 3: 评审提案

Step 4: 执行实现（Apply）

Step 5: 归档变更（Archive）

7. 最佳实践与避坑指南

7.1 有效使用 OpenSpec

7.2 规范文件写作建议

7.3 团队协作建议

7.4 模型选择建议

7.5 常见问题解决

8. 与同类工具对比

8.1 工具对比表

8.2 为什么选择 OpenSpec？

8.3 资源链接

附录

A. CLI 命令参考

B. 文件结构参考

C. 术语表

4.1 `/opsx:explore` —— 探索想法（Thinking Partner）

4.2 `/opsx:propose` —— 创建提案（Change Proposal）

4.3 `/opsx:apply` —— 执行实现（Implementation）

4.4 `/opsx:archive` —— 归档变更（Archive）