初识OpenSpec

推荐语

探索规范驱动开发新利器OpenSpec，让AI编程更精准高效！

核心内容：
1. OpenSpec如何解决传统AI编码助手的四大痛点
2. 规范驱动开发的核心工作流程解析
3. 快速上手指南与多平台支持特性

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

小伙伴们大家好，我是小溪，见字如面。前面我们初步认识了Github开源的SDD工具包Spec Kit，今天我们来了解另一款优秀的SDD开源工具OpenSpec。对Spec Kit还不了解的小伙伴可以看往期内容：

• 初识Spec Kit

当前使用版本

openspec 0.16.0

优势

• 开源免费

• 适用于 0→1 和 1→N 的项目

• 多平台支持

限制

• 对OpenSpec的使用流程需要有一定的了解

简介

OpenSpec是一个规范驱动开发工具，专门为AI编程助手设计。它通过结构化的变更文件夹（提案、任务和规范更新）来保持范围的明确性和可审计性，让人类和AI利益相关者在工作开始前就达成一致。

规范驱动开发（SDD）的核心理念是：先定义规范，再让 AI 按规范施工。

Github地址：https://github.com/Fission-AI/OpenSpec

核心功能

• 🚀 轻量级：无需API密钥，最小化设置

• 🔄 现有项目优先：特别适合修改现有功能 (1→n)

• 📋 变更跟踪：提案、任务和规范差异的完整生命周期管理

• 🤖 AI工具集成：支持多种主流AI编码助手

为什么需要OpenSpec？

传统AI编码助手的问题：

• 需求描述模糊：通过自然语言一句话描述或者表达存在歧义，AI 只能"猜测"我们的意图

• 上下文缺失：AI 不知道项目的整体架构和约束条件，经常遗漏重要功能、添加不必要的功能

• 标准缺失：没有明确的输入输出规范，AI 只能自由发挥导致代码不可预测

• 文档滞后：代码和文档分离，一改就过期

OpenSpec通过规范驱动开发解决这些问题：

• 明确共识：在编码前确定所有要求，技术规范达成一致

• 结构化变更：所有相关文档集中管理，结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计

• 可审查输出：AI根据明确规范生成代码，共享对已提议、正在进行或已存档内容的可见性

• 版本控制：完整追踪所有变更历史

工作流程

OpenSpec的工作流程大致如下：

• 起草变更提案：通过自然语言描述想要实现功能需求，AI会分析需求询问关键细节、生成完整提案文档、设计文档、罗列任务清单、创建规范增量

• 审查对齐：与AI助手一起审查提案，对齐遗漏，直到规范统一得到所有人认可

• 实施任务：严格按照规范实施开发任务，逐一完成任务清单，标记任务进度

• 存档更新：变更归档保存，将批准的规范合并到项目规范文档

安装配置

前置条件

• Node.js 20.19.0及以上版本

安装OpenSpec CLI

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

在命令行输入以下命令验证安装，输出版本号表示安装成功

基本使用

支持的平台

命令行指令

OpenSpec提供了一套用于管理OpenSpec规范的命令行指令，这在查看和验证规范时很重要，在命令行终端输入 openspec -h 可以查看完整的命令行帮助文档

• init：在项目中初始化OpenSpec，示例：openspecinit [options] [path]

• update：更新OpenSpec说明文件，示例：openspec update [path] 

• list：列出项目（默认列出变更）。使用 --specs 可列出规范。示例：openspec list [options] 

• view：以交互式仪表板形式展示规范与变更

• change：管理OpenSpec变更提案，⚠️废弃了建议使用list

• archive：归档已完成的变更并更新主规范，示例：openspec archive [options] [change-name]

• spec：管理和查看OpenSpec规范

• validate：验证变更与规范，示例：openspec validate [options] [item-name] 

• show：显示某一变更或规范，示例：openspec show [options] [item-name] 

• help：显示指定命令的帮助信息，示例：openspec help [command]

OpenSpec目录结构

OpenSpec的 提案变更、验证、执行 和 归档 管理严格依赖OpenSpec的目录结构，一个完整的OpenSpec目录结构大致如下：

openspec/├── project.md             # 项目规范约定├── AgentS.md              # 为Agent提供的OpenSpec使用说明，一般不需要动├── specs/                 # 源规范目录，每次变更归档后会合并到这里│       ├── spec.md        # 源需求和场景规范│       └── design.md      # 源技术模式├── changes/                # 提案变更目录│   ├── [change-name]/     # 单个提案变更│   │   ├── proposal.md     # 为什么，什么，影响│   │   ├── tasks.md        # 实施检查清单│   │   ├── design.md       # 技术决策（可选；见标准）│   │   └── specs/          # 增量变更规范│   │       └── [capability]/│   │           └── spec.md # ADDED/MODIFIED/REMOVED│   └── archive/            # 已完成的提案变更

初始化项目

在使用OpenSpec之前需要进行初始化，主要是在项目中创建OpenSpec依赖的目录结构。初始化项目也很简单，直接在命令行终端输入指令：

$ openspec init

初始化过程分为3步，第一步为OpenSpec的简介，直接回车即可

第二步为AI开发工具选择，OpenSpec兼容了所有目前主流的AI开发工具，选择自己使用的AI开发工具会创建对应AI工具的自定义命令配置

回车继续，第三步为信息确认，直接完成配置即可

初始化完成后，OpenSpec会提供一个使用引导

Next steps - Copy these prompts to Antigravity:────────────────────────────────────────────────────────────1. Populate your project context:   "Please read openspec/project.md and help me fill it out    with details about my project, tech stack, and conventions"2. Create your first change proposal:   "I want to add [YOUR FEATURE HERE]. Please create an    OpenSpec change proposal for this feature"3. Learn the OpenSpec workflow:   "Please explain the OpenSpec workflow from openspec/AGENTS.md    and how I should work with you on this project"

• 梳理项目信息填充到 openspec/project.md 文件

• 创建变更提案示例

• 让AI从 openspec/AGENTS.md 文件学习OpenSpec工作流的使用方式

初始化完成，我们将得到如的项目结构，包括 自定义指令、OpenSpec目录、AGENTS.md

梳理项目功能

OpenSpec初始化完成后，第一步是需要让AI熟悉项目，可以使用初始化OpenSpec提供的引导建议，直接复制指导建议

AI会为我们 熟悉项目更新 openspec/project.md、熟悉OpenSpec工作流程 、创建第一个提案

并给出下一步建议

更新后的OpenSpec目录结构如下：

如果我们熟悉了OpenSpec，也可以直接通过提示词完成项目梳理

熟悉项目功能、技术栈等信息并填充 @project.md 

创建变更提案

创建变更提案是开始一个需求的第一步，可以使用自然语言描述需求创建提案

创建一个 OpenSpec 变更提案，用于添加一个注册登录页面

可以使用OpenSpec提供的自定义命令

/openspec:proposal 添加一个注册登录页面

对于描述模糊的需求，AI会向我们提问，我真对问题做出对应回答

确定需要澄清的问题1. 认证方式：本地存储，不需要后端API支持，前端本地存储即可2. 功能范围：不需要忘记密码，不需要三方登录，只提供默认账号密码登录3. 路由策略：安装 Vue Router 来处理页面导航，登录后跳转到首页4. 与现有变更的关系：创建新的变更提案，登录页面独立实现

补充完疑问后，AI会根据完整的需求再次创建提案，可以看到AI根据OpenSpec规则要求创建了提案所需的目录结构并对提案进行验证（只有提案验证通过后才能进行下一步）

提案创建完成后，我们可以得到一个新的变更目录 openspec/changes/add-auth-pages，目前结构如下：

add-auth-pages├── design.md          # 针对提案需求的设计方案├── proposal.md        # 变更提案需求说明，包含Why、What和Impact└── specs/│  └── auth/│    ├── spec.md      # 授权规范│  └── routing/│    ├── spec.md      # 路由规范└── tasks.md           # 针对提案需求拆分的开发任务

提案创建完成后也可以对提案进行反复补充更新

验证提案

在提案变更后，如果AI工具没有自动验证，我们也可以对提案变更进行手动验证

$ openspec validate add-auth-pages --strict

实施任务

提案及验证都完成后，就可以进行实施阶段了，可以使用自然语言描述实施变更提案

实施 add-auth-pages 变更提案

也可以使用OpenSpec提供的自定义命令

/openspec-apply add-auth-pages

AI会根据OpenSpec提供的变更提案规范执行开发任务，任务执行完成后会同步更新任务状态

实施阶段也是可以对规范进行补充的，有不满意的地方直接提，直到满意为止

也可以将调整后的样式规范更新到变更提案中

归档变更

实施开发完成后，就可以进入到了最后一步归档了，归档变更的作用是把提案 specs 合并到主目录 openspec/specs/使其成为项目的正式规范。

同样可以使用自然语言描述进行归档变更

归档变更 add-auth-pages

可以使用OpenSpec提供的自定义命令

/openspec-archive add-auth-pages

也可以使用OpenSpec命令行指令

$ openspec archive add-auth-pages

归档完成后可以看到，OpenSpec将 changes/add-auth-pages 提案移动到了 changes/archive 目录下并打上归档时间，同时将 changes/add-auth-pages/specs 合并到了 openspec/specs 目录下

至此一个完整的需求变更就完成了

点击关注，及时接收最新消息