小伙伴们大家好，我是小溪，见字如面。前面我们初步认识了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 目录下
至此一个完整的需求变更就完成了
