OpenSpec小白快速上手指南
你是不是在用 AI 编程助手的时候，经常遇到这些问题：
- 跟 AI 说了半天需求，写着写着它就忘了之前的约定？
- AI 生成的代码总是跑偏，改了好几遍还是不对，反复返工？
- 团队协作的时候，大家对需求的理解不一样，沟通成本很高？
如果你有这些烦恼，那 OpenSpec 就是为你准备的！它能让你的 AI 编程从「凭感觉」变成「可预测」，小白也能 10 分钟快速上手。
一、先搞懂：OpenSpec 到底是什么？
简单来说，OpenSpec 是一个规范驱动开发的工具，专门给 Cursor、Claude 这些 AI 编程助手设计的。
它的核心理念非常简单：先定规矩，再写代码。
- 你先把「要做什么、怎么做、分几步做」写成标准化的文档
- AI 严格按照这个文档来生成代码，不会瞎猜，也不会忘需求
- 所有的变更都有记录，后续维护、复盘都很方便
它不是什么复杂的框架，零侵入你的现有项目，装完就能用，完全不用改你原来的开发流程。
二、环境准备：30 秒检查你的电脑
在安装之前，先确认你的电脑满足两个简单的要求：
1. 检查 Node.js 版本
OpenSpec 需要 Node.js 20.19.0 及以上版本。
打开你的终端（Windows 用 CMD 或者 PowerShell，Mac/Linux 用终端），输入这个命令检查版本：
node --version
如果输出版本号大于等于 v20.19.0，那就没问题。
如果版本太低，推荐用 nvm 来升级，或者去 Node.js 官网 下载最新的 LTS 版本。
2. 国内用户先配置镜像（可选但推荐）
如果你是国内用户，安装的时候可能会遇到网络慢的问题，先执行这个命令配置淘宝镜像，能快很多：
npm config set registry https://registry.npmmirror.com
三、1 分钟安装 OpenSpec
确认环境没问题之后，安装 OpenSpec 只需要一条命令！
全局安装
在终端里输入：
# 使用 npm 安装（大多数人用这个）
npm install -g @fission-ai/openspec@latest
# 如果你用 pnpm（更快）
pnpm install -g @fission-ai/openspec@latest
# 如果你用 yarn
yarn global add @fission-ai/openspec@latest
验证安装是否成功
安装完之后，输入这个命令检查：
openspec --version
如果能输出版本号，比如 v1.x.x，那就说明安装成功啦！
四、2 分钟初始化你的项目
安装完工具，接下来只需要在你的项目里初始化一下就可以用了。
1. 进入你的项目目录
首先用 cd 命令进到你要开发的项目文件夹里，比如：
cd 你的项目文件夹路径
# 比如 cd ~/code/my-web-project
2. 执行初始化命令
然后执行初始化命令，如果你用的是 Cursor 编辑器（最常用的 AI 编辑器），推荐用这个命令：
openspec init --tools cursor
如果你用的是 Claude Code，就改成：
openspec init --tools claude
如果你想支持所有工具，直接执行：
openspec init --tools all
3. 重启你的编辑器
初始化完成之后，一定要重启一下你的编辑器！比如关掉 Cursor 再重新打开，这样编辑器才能识别 OpenSpec 的快捷命令。
五、核心工作流：4 步搞定开发
初始化完成之后，你就可以用 OpenSpec 的标准工作流来开发了，整个流程非常简单：
1. 第一步：提案（Propose）—— 告诉 AI 你要做什么
这一步是把你的想法告诉 AI，AI 会自动帮你生成完整的需求文档。
打开你编辑器的 AI 聊天框，输入这个命令：
/opsx:propose "我要做一个待办事项功能，用户可以添加、标记完成、删除任务，数据存在本地"
输入之后，AI 会自动帮你创建一个变更文件夹，并且生成 4 个核心文档：
proposal.md：为什么要做这个功能，要改什么specs/：详细的功能需求规范design.md：技术设计方案tasks.md：拆分好的实现任务清单
你不用自己写这些文档，AI 会帮你搞定！
2. 第二步：规范（Spec）—— 确认需求没有问题
AI 生成完文档之后，你只需要检查一下这些文档，看看有没有漏的需求，有没有不对的地方。
比如你可以看看 tasks.md 里的任务是不是拆分的合理，spec.md 里的功能是不是你想要的，有问题的话直接改文档就行，不用跟 AI 反复说。
3. 第三步：实现（Apply）—— AI 按规范自动写代码
确认规范没问题之后，只需要在聊天框里输入：
/opsx:apply
然后 AI 就会严格按照刚才的规范文档，逐个完成任务，自动生成代码！你不用再跟 AI 反复解释需求，它会严格按照之前定好的规矩来写，不会跑偏，也不会忘需求。
4. 第四步：归档（Archive）—— 留存记录，清理目录
功能写完、测试没问题之后，最后一步就是归档：
/opsx:archive
这个命令会把这次的变更记录归档起来，以后你想查这个功能当时是怎么设计的，直接看归档记录就行，同时也会把你的项目规范更新，保持目录整洁。
六、5 分钟实战：跟着做一遍就会了
我们用一个最简单的「待办事项」功能，带你完整走一遍流程，你跟着敲命令，5 分钟就能跑通整个流程！
步骤 1：创建变更
首先在终端里，进入你的项目目录，创建一个新的变更：
openspec new change todo-list
这会在 openspec/changes/ 下面创建一个 todo-list 的文件夹，用来放这次变更的所有文档。
步骤 2：完善规范文档
你可以自己手动写这几个文档，也可以直接用 AI 帮你生成，这里我们用最简单的方式，直接写好示例内容：
1. 提案文档 proposal.md
打开 openspec/changes/todo-list/proposal.md，写入：
## Why
需要实现轻量级待办事项功能，满足用户日常任务管理需求，本地存储无需后端。
## What Changes
- 新增待办事项添加功能
- 支持标记完成/未完成状态
- 支持删除待办事项
- 数据存储在localStorage
## Capabilities
New: todo-list（待办事项管理）
2. 需求规范 spec.md
打开 openspec/changes/todo-list/specs/todo-list/spec.md，写入：
# 待办事项功能规范
## 功能需求
1. 输入框添加任务，回车确认
2. 任务列表展示所有事项，已完成划横线
3. 点击复选框切换完成状态
4. 点击删除按钮移除任务
5. 页面刷新数据不丢失
## 非目标
- 不实现云端同步、分类、筛选
3. 技术设计 design.md
打开 openspec/changes/todo-list/design.md，写入：
# 技术设计
- 技术栈：HTML + CSS + JavaScript
- 数据存储：localStorage
- 核心逻辑：
1. 读取本地数据渲染列表
2. 绑定添加、切换、删除事件
3. 数据变更同步更新本地存储
4. 任务清单 tasks.md
打开 openspec/changes/todo-list/tasks.md，写入：
- [ ] 1. 创建HTML结构（输入框、列表、删除按钮）
- [ ] 2. 编写CSS样式，适配完成/未完成状态
- [ ] 3. 实现localStorage数据读写逻辑
- [ ] 4. 实现添加任务功能
- [ ] 5. 实现状态切换功能
- [ ] 6. 实现删除任务功能
- [ ] 7. 页面加载自动渲染数据
步骤 3：让 AI 自动实现代码
打开 Cursor 的聊天框，输入：
/opsx:apply todo-list
然后你就等着就行！AI 会自动按照上面的任务，逐个生成代码，最后给你一个完整的、可以直接运行的待办事项功能！
步骤 4：归档
功能写完测试没问题之后，在终端里执行：
openspec archive todo-list
搞定！整个流程就走完了，是不是很简单？
七、常用命令速查：不用记，用的时候查就行
终端 CLI 命令
| 命令 | 作用 |
|---|---|
openspec init --tools cursor | 初始化项目，配置 Cursor 支持 |
openspec new change 变更名 | 创建一个新的功能变更 |
openspec list | 查看所有正在进行中的变更 |
openspec show 变更名 | 查看某个变更的详细信息 |
openspec validate 变更名 | 检查规范文档的格式是否正确 |
openspec archive 变更名 | 归档已经完成的变更 |
openspec update | 更新 OpenSpec 的 AI 指令，升级版本后用 |
AI 编辑器斜杠命令
| 命令 | 作用 |
|---|---|
/opsx:propose "你的想法" | 创建变更，自动生成所有规范文档 |
/opsx:explore | 需求不明确的时候，先跟 AI 探索方案 |
/opsx:apply | 让 AI 按照规范自动实现代码 |
/opsx:archive | 归档完成的变更 |
/opsx:onboard | 交互式引导教程，新手可以用这个快速熟悉 |
注意：Cursor 里的命令是
opsx-propose（横杠），Claude Code 里是opsx:propose（冒号），别搞混啦！
八、小白常见问题：踩过的坑都帮你踩好了
1. 安装的时候提示权限错误？
Windows 用户试试用管理员身份打开终端，Mac 用户可以在命令前面加 sudo：
sudo npm install -g @fission-ai/openspec@latest
2. 输入斜杠命令，AI 说不认识？
- 首先确认你已经执行了
openspec init - 然后重启一下你的编辑器，这是最常见的原因！
- 如果还不行，执行
openspec update重新生成一下指令文件
3. 提示 "Change not found"？
- 检查你是不是输错了变更名
- 执行
openspec list看看当前有哪些变更 - 确认你是不是在正确的项目目录里
4. 什么时候用 OpenSpec？什么时候不用？
✅ 推荐用的场景：
- 开发新功能
- 复杂的重构
- 团队协作的项目
- 用 AI 写代码的时候
❌ 不用的场景：
- 改一行代码的小 Bug
- 临时的测试脚本
- 生产环境的紧急修复（先修复，事后补文档就行）
九、最佳实践：让你用得更顺的小技巧
- 永远先写规范，再写代码：别跳过这一步，这是 OpenSpec 最核心的价值，跳过了就跟没用一样。
- 任务拆细一点：
tasks.md里的每个任务，最好控制在 1-2 小时能做完，AI 实现起来更精准。 - 配置项目上下文：编辑
openspec/config.yaml，把你的技术栈、编码规范写进去，AI 生成的代码会更贴合你的项目。 - 及时归档：功能写完就归档，别把
changes目录堆得乱七八糟，归档完历史记录也能留存下来。 - 小步迭代：一次变更只做一个小功能，别把一堆功能塞到一个变更里，容易乱。
最后
OpenSpec 真的非常简单，不用学复杂的概念，跟着上面的步骤，10 分钟就能跑通整个流程，从此告别 AI 编程的返工和幻觉，让你的开发效率翻倍！
现在就打开你的终端，装起来试试吧！
