前言

AI 编程时代，我们一边享受高效生成，一边被需求模糊、AI 幻觉、反复返工、代码不可控困扰。写代码前没有统一规范，AI 凭感觉生成，开发者反复修改，团队协作效率极低。

OpenSpec 就是解决这一痛点的开源利器 —— 它是 Fission AI 推出的规范驱动开发（SDD）框架，通过「先定规范、再写代码」的标准化流程，让 AI 严格按规则生成代码，实现需求、设计、实现、归档全链路可追溯、可管控。

本文从入门概念、核心原理、环境搭建、完整实战、最佳实践五个维度，带你从零掌握 OpenSpec，让 AI 编程从「凭感觉」变成「可预测」。

一、OpenSpec 到底是什么？

1.1 核心定义

OpenSpec 是轻量级、开源、AI 友好的规范驱动开发工具，专为 Cursor、Claude、Copilot 等 AI 编程助手设计，核心是通过标准化文档约束 AI 行为，让开发流程更可控、代码更规范、协作更高效。

1.2 核心理念：先 Spec，后 Code

• Spec（规范）：明确「要做什么、怎么做、分几步做」，是人和 AI 的统一契约；
• Code（代码）：AI 严格按照规范生成，杜绝猜测、减少幻觉、避免偏离需求。

1.3 核心价值

AI 编程可控：AI 不再自由发挥，完全遵循规范生成代码全流程可追溯：从需求提案到功能归档，每一步都有记录 团队协作高效：统一规范消除沟通偏差，新人快速上手 兼容主流 AI 工具：原生支持 Cursor、Claude、Copilot 等零侵入集成：不破坏现有项目结构，一键初始化即可使用

二、OpenSpec 核心架构与工作流

2.1 核心目录结构

初始化后项目自动生成规范目录，结构清晰、分工明确：

plaintext

your-project/
├── openspec/                # 核心规范目录
│   ├── config.yaml          # 项目配置（技术栈、约束规则）
│   ├── specs/               # 最终生效规范（项目唯一可信源）
│   ├── changes/             # 待实现变更提案（开发中）
│   │   └── 变更名称/        # 单个功能完整规范
│   │       ├── proposal.md  # 变更提案（为什么做、做什么）
│   │       ├── specs/       # 需求与功能规范
│   │       ├── design.md    # 技术设计方案
│   │       └── tasks.md     # 可执行任务清单
│   └── archive/             # 已完成变更归档（历史记录）
└── .cursor/                 # AI工具集成配置（自动生成）

2.2 标准工作流（4 步走完开发全流程）

1. 提案（Propose）：创建功能变更，定义需求、范围、目标；
2. 规范（Spec）：完善需求规格、技术设计、任务拆解；
3. 实现（Apply）：AI 按规范生成代码，开发者校验调整；
4. 归档（Archive）：功能完成后合并规范，留存历史记录。

三、环境搭建：10 分钟快速上手

3.1 前置条件

• Node.js 20.19.0 及以上版本
• npm/pnpm 包管理器
• AI 编辑器：Cursor（推荐）、Claude Code、VS Code

3.2 安装 OpenSpec CLI

bash

运行

# 全局安装最新版
npm install -g @fission-ai/openspec@latest

# 验证安装（输出版本号即成功）
openspec --version

3.3 项目初始化

bash

运行

# 进入项目目录
cd your-project

# 初始化并配置Cursor（推荐）
openspec init --tools cursor

# 重启IDE，让AI斜杠命令生效

3.4 常用命令速查

表格

命令	作用
openspec new change 变更名	创建新功能变更
openspec list	查看所有待实现变更
openspec show 变更名	查看变更详情
openspec validate 变更名	校验规范格式
openspec archive 变更名	归档已完成变更

3.5 AI 编辑器快捷命令

• /opsx:propose "功能描述"：一键生成变更提案
• /opsx:apply 变更名：AI 按规范实现代码
• /opsx:archive 变更名：归档完成的功能

四、完整实战：用 OpenSpec 实现「待办事项」功能

以待办事项（TODO） 功能为例，完整演示 OpenSpec 从 0 到 1 的开发流程。

4.1 创建变更提案

bash

运行

# 创建名为todo-list的变更
openspec new change todo-list

4.2 完善规范文件

1. proposal.md（变更提案）

plaintext

## Why
需要实现轻量级待办事项功能，满足用户日常任务管理需求，本地存储无需后端。

## What Changes
- 新增待办事项添加功能
- 支持标记完成/未完成状态
- 支持删除待办事项
- 数据存储在localStorage

## Capabilities
New: todo-list（待办事项管理）

2. specs/todo-list/spec.md（需求规范）

plaintext

# 待办事项功能规范
## 功能需求
1. 输入框添加任务，回车确认
2. 任务列表展示所有事项，已完成划横线
3. 点击复选框切换完成状态
4. 点击删除按钮移除任务
5. 页面刷新数据不丢失

## 非目标
- 不实现云端同步、分类、筛选

3. design.md（技术设计）

plaintext

# 技术设计
- 技术栈：HTML + CSS + JavaScript
- 数据存储：localStorage
- 核心逻辑：
  1. 读取本地数据渲染列表
  2. 绑定添加、切换、删除事件
  3. 数据变更同步更新本地存储

4. tasks.md（任务清单）

plaintext

- [ ] 1. 创建HTML结构（输入框、列表、删除按钮）
- [ ] 2. 编写CSS样式，适配完成/未完成状态
- [ ] 3. 实现localStorage数据读写逻辑
- [ ] 4. 实现添加任务功能
- [ ] 5. 实现状态切换功能
- [ ] 6. 实现删除任务功能
- [ ] 7. 页面加载自动渲染数据

4.3 AI 按规范实现代码

在 Cursor 中输入：

plaintext

/opsx:apply todo-list

AI 将严格按照 tasks.md 和 spec.md，生成完整的 HTML、CSS、JS 代码，无需反复调整。

4.4 功能校验与归档

bash

运行

# 校验规范格式
openspec validate todo-list

# 归档已完成功能（合并到正式规范）
openspec archive todo-list

4.5 实战效果

• 一键生成完整可运行的待办事项功能
• 代码完全符合规范，无冗余、无偏离需求
• 所有变更记录留存，便于后续维护

五、OpenSpec 最佳实践

1. 规范先行：永远先写 proposal 和 spec，再让 AI 生成代码；
2. 任务细粒度：单个任务控制在 1-2 小时内完成，便于 AI 精准实现；
3. 配置上下文：在 config.yaml 中填写技术栈、规范，减少 AI 猜测；
4. 及时归档：功能完成立即归档，保持 changes 目录整洁；
5. 团队统一：全团队使用同一套规范，消除协作偏差；
6. 小步迭代：单次变更只做一个功能，避免复杂耦合。

六、适用场景与避坑指南

6.1 适合场景

✅ 中大型功能开发、团队协作项目✅ 长期维护、需要文档沉淀的项目✅ AI 辅助编程、追求代码可控的开发者✅ 金融、企业级等高质量要求场景

6.2 不适合场景

❌ 快速原型验证、一次性脚本❌ 简单 bug 修复、单文件小修改❌ 无维护价值的临时项目

6.3 常见避坑

• 不要跳过规范直接写代码，失去 OpenSpec 核心价值；
• 规范不要过于简略，否则 AI 仍会猜测需求；
• 不要一次性创建过多变更，并行开发易混乱。

七、总结

OpenSpec 不是复杂的框架，而是AI 编程的「规范契约」—— 它用最简单的方式，把「凭感觉的 AI 编程」变成「可预测、可管控、可追溯的规范开发」。

对于个人开发者，它能减少返工、提升效率；对于团队，它能统一标准、降低协作成本。在 AI 全面赋能开发的今天，OpenSpec 已经成为高效、可控 AI 编程的必备工具。

从openspec init开始，5 分钟搭建规范流程，让你的 AI 编程告别幻觉、精准落地！