初识OpenSpec - 技术栈

小伙伴们大家好，我是小溪，见字如面。前面我们初步认识了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地址：github.com/Fission-AI/...

核心功能

🚀 轻量级：无需API密钥，最小化设置
🔄 现有项目优先：特别适合修改现有功能 (1→n)
📋 变更跟踪：提案、任务和规范差异的完整生命周期管理
🤖 AI工具集成：支持多种主流AI编码助手

为什么需要OpenSpec？

传统AI编码助手的问题：

需求描述模糊：通过自然语言一句话描述或者表达存在歧义，AI 只能"猜测"我们的意图
上下文缺失：AI 不知道项目的整体架构和约束条件，经常遗漏重要功能、添加不必要的功能
标准缺失：没有明确的输入输出规范，AI 只能自由发挥导致代码不可预测
文档滞后：代码和文档分离，一改就过期

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

明确共识：在编码前确定所有要求，技术规范达成一致
结构化变更：所有相关文档集中管理，结构化的变更文件夹（提案、任务和规范更新）使范围明确且可审计
可审查输出：AI根据明确规范生成代码，共享对已提议、正在进行或已存档内容的可见性
版本控制：完整追踪所有变更历史

工作流程

OpenSpec的工作流程大致如下：

起草变更提案：通过自然语言描述想要实现功能需求，AI会分析需求询问关键细节、生成完整提案文档、设计文档、罗列任务清单、创建规范增量
审查对齐：与AI助手一起审查提案，对齐遗漏，直到规范统一得到所有人认可
实施任务：严格按照规范实施开发任务，逐一完成任务清单，标记任务进度
存档更新：变更归档保存，将批准的规范合并到项目规范文档

安装配置

前置条件

Node.js 20.19.0及以上版本

安装OpenSpec CLI

shell 复制代码

$ 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目录结构大致如下：

bash 复制代码

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依赖的目录结构。初始化项目也很简单，直接在命令行终端输入指令：

shell 复制代码

$ openspec init

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

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

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

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

sql 复制代码

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，也可以直接通过提示词完成项目梳理

css 复制代码

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

创建变更提案

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

js 复制代码

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

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

bash 复制代码

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

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

markdown 复制代码

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

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

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

cs 复制代码

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

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

验证提案

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

sql 复制代码

$ openspec validate add-auth-pages --strict

实施任务

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

cs 复制代码

实施 add-auth-pages 变更提案

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

bash 复制代码

/openspec-apply add-auth-pages

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

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

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

归档变更

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

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

cs 复制代码

归档变更 add-auth-pages

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

bash 复制代码

/openspec-archive add-auth-pages

也可以使用OpenSpec命令行指令

powershell 复制代码

$ openspec archive add-auth-pages

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

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

友情提示

见原文：初识OpenSpec

本文同步自微信公众号 "程序员小溪" ，这里只是同步，想看及时消息请移步我的公众号，不定时更新我的学习经验。友情提示友情提示