OpenSpec - AI 编程的规范驱动开发框架
约 1086 字大约 4 分钟
AI开发工具开源项目
2026-03-26
简介
OpenSpec 是由 Fission AI 开发的 Spec-Driven Development(规范驱动开发,SDD)框架,专为 AI 编程助手设计。它在人与 AI 之间添加了一层轻量级的规范层,确保双方在写代码之前先就「要构建什么」达成一致。
简单来说:先对齐需求,再动手写码。
解决什么问题?
使用 AI 编程助手(Cursor、Claude Code、Copilot 等)时,常见痛点:
- AI 理解偏差:需求描述模糊时,AI 写出的代码与预期不符
- 缺乏追溯性:改了什么、为什么改、改动范围多大,没有结构化记录
- 上下文丢失:对话越长,AI 越容易偏离最初目标
- 多次变更冲突:多个功能并行开发时,规范和代码容易打架
OpenSpec 通过结构化的 proposal → spec → design → task 工作流,让每次变更都有据可查、有章可循。
核心概念
制品结构
每个变更(change)包含四类制品:
| 制品 | 作用 |
|---|---|
proposal.md | 捕获意图、范围和高层方案(为什么做) |
specs/(delta specs) | 记录相对于当前规范的增/改/删(做什么) |
design.md | 技术实现方案和架构决策(怎么做) |
tasks.md | 可执行的实现清单(按步骤做) |
Delta 规范
OpenSpec 使用 delta 规范 而非全量重写——只记录变更部分(ADDED / MODIFIED / REMOVED)。这避免了多个变更触及同一区域时的冲突,天然适合 brownfield(存量项目)开发。
安装与配置
前置要求: Node.js >= 20.19.0
# 全局安装
npm install -g @fission-ai/openspec@latest
# 进入项目目录,初始化
cd your-project
openspec init也支持 pnpm、yarn、bun、nix 等包管理器。
初始化后的项目结构:
openspec/
├── specs/ # 权威系统文档,按领域组织
├── changes/ # 每次修改的独立文件夹
└── config.yaml # 可选的项目配置使用方式
快速三步流程
# 1. 提议变更
/opsx:propose add-dark-mode
# 2. 执行实现
/opsx:apply add-dark-mode
# 3. 归档完成
/opsx:archive add-dark-mode完整工作流
# 探索阶段(不确定做什么时)
/opsx:explore performance-improvements
# 创建变更 → 逐步生成制品 → 实现 → 验证 → 归档
/opsx:new → /opsx:ff 或 /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive完整命令列表
| 命令 | 用途 |
|---|---|
/opsx:propose | 一次性创建变更文件夹 + 所有规划制品 |
/opsx:explore | 开放式探索,不创建制品 |
/opsx:apply | 按任务清单执行实现 |
/opsx:archive | 归档已完成的变更 |
/opsx:new | 创建变更文件夹,等待手动添加制品 |
/opsx:continue | 逐个创建制品(分步推进) |
/opsx:ff | 快进:按顺序创建所有规划制品 |
/opsx:verify | 验证实现是否符合规范(完整性、正确性、一致性) |
/opsx:sync | 将 delta 规范合并到主规范目录 |
/opsx:bulk-archive | 批量归档多个已完成的变更 |
/opsx:onboard | 交互式教程(15-30 分钟,使用你的真实代码库) |
实际示例
以添加暗色模式为例:
# 第 1 步:提议变更
> /opsx:propose add-dark-mode
# AI 自动创建:
# openspec/changes/add-dark-mode/
# proposal.md -- 为什么要做,变更范围
# specs/ -- delta 规范(新增/修改/删除)
# design.md -- 技术方案(Context Provider、CSS 变量等)
# tasks.md -- 实现清单
# 第 2 步:人工审查,与 AI 讨论调整
# 第 3 步:执行实现
> /opsx:apply add-dark-mode
# AI 逐项完成任务:
# [x] 添加 ThemeContext Provider
# [x] 创建 DarkModeToggle 组件
# [x] 添加 CSS 自定义属性
# [x] 集成 localStorage 持久化
# 第 4 步:验证(可选)
> /opsx:verify add-dark-mode
# 第 5 步:归档
> /opsx:archive add-dark-mode支持的 AI 工具
OpenSpec 支持 24 款 AI 编程工具,包括:
Claude Code、Cursor、GitHub Copilot、Windsurf、Gemini CLI、Amazon Q Developer、Cline、Kiro、RooCode、Trae、Codex、Continue、Qwen Code 等。
不同工具的命令语法略有差异,例如 Cursor 使用
/opsx-propose(连字符替代冒号)。
设计哲学
- 流动而非僵化:没有阶段门禁,可以按任意顺序创建制品
- 迭代而非瀑布:随时调整、随时验证
- 简单而非复杂:最小化配置和仪式感
- 存量优先:专为修改现有代码库设计,而非仅适用于全新项目
相关链接
- GitHub:Fission-AI/OpenSpec
- 官网:openspec.dev
- Discord:社区讨论
- 协议:MIT
