别再让 AI 编程瞎猜！OpenSpec 让你和 AI 助手高效协作不返工

当下AI编程助手越来越普及，可你是不是总遇到这些问题：跟AI说要做个功能，结果它生成的代码完全跑偏；需求描述稍微模糊一点，就得反复修改代码；多人协作时，AI生成的代码风格五花八门，后期维护头大？

如果你也有这些困扰，那今天要介绍的OpenSpec绝对是你的救星！它是专为AI编码助手打造的规范驱动开发工具，核心就是让你和AI在写代码前，先在「要做什么」上达成高度共识，从根源上解决AI编程的各种痛点。接下来就跟大家好好聊聊，为什么要用OpenSpec、它能做什么，以及如何快速上手这个工具。

一、为什么一定要用OpenSpec？

传统的AI编程，本质上是「靠嘴说需求，靠AI猜结果」，而OpenSpec带来的是规范驱动开发的全新模式，这也是它能解决传统AI编程痛点的关键。

1. 告别AI猜需求，从源头避免返工：就像盖房子要先画施工图，OpenSpec要求写代码前先定义清晰的规范，AI严格按照规范生成代码，再也不会出现「你要的是A，AI给的是B」的情况。
2. 需求不再模糊，协作更高效：不管是个人开发还是团队协作，OpenSpec都会用结构化的文档把需求、设计、任务写得明明白白，再也不用为「当初说的不是这个意思」扯皮。
3. 统一代码标准，降低维护成本：基于同一套规范生成的代码，风格和质量更统一，后期迭代、维护时，不管是自己看还是团队成员接手，都能快速理解。
4. 大幅降低开发成本：实测数据显示，用OpenSpec后，AI开发的平均成本能降低75%-87%，核心原因就是减少了无效的对话和重复的代码生成，提升了AI单次生成代码的准确率。

除此之外，OpenSpec对存量项目和新项目都友好，不用大改现有代码就能接入，还支持Cursor、Claude Code、GitHub Copilot等主流AI编程助手，不用换工具，直接无缝衔接。

二、OpenSpec到底能做什么？

简单来说，OpenSpec就是你和AI编程助手之间的「沟通桥梁」+「项目管理助手」，核心是通过标准化的工作流和结构化的项目文档，让AI编程的全流程清晰、可控、可追溯。

1. 提供两种灵活的工作流，适配不同开发场景

不管是简单的小功能迭代、Bug修复，还是复杂的跨服务开发、核心重构，OpenSpec都有对应的工作流，不用自己摸索流程：

• 快速工作流（核心模式）：/opsx:propose（提案）→/opsx:apply（应用）→/opsx:archive（归档），三步搞定简单需求，高效快捷。
• 扩展工作流（自定义模式）：/opsx:new→/opsx:ff/continue→/opsx:apply→/opsx:verify（验证）→/opsx:archive，多了验证环节，适合需要严谨把控的复杂开发场景。

2. 自动生成标准化项目结构，规范管理所有内容

在项目中执行openspec init后，会自动生成专属的openspec/目录，所有规范、变更都在这个目录里管理，结构清晰，一眼就能看懂：

openspec/
├── specs/              # 项目「真理仓库」：记录系统当前的实际行为，按功能域分类
│   └── <domain>/       # 比如auth（认证）、ui（界面）、payments（支付）
│       └── spec.md
├── changes/            # 变更暂存区：每个需求/修改都有独立文件夹，互不干扰
│   └── <change-name>/  # 比如add-dark-mode（添加暗黑模式）
│       ├── proposal.md # 为什么改、改什么
│       ├── design.md   # 怎么改、技术方案是什么
│       ├── tasks.md    # 实现清单，带勾选框，做完一项勾一项
│       └── specs/      # 增量规范：记录具体要新增/修改/删除的内容
└── config.yaml         # 项目配置（可选）

其中specs/和changes/是核心目录：specs/是项目的「活文档」，是AI生成代码的唯一依据；changes/存放所有待实现的变更，完成后会合并到specs/，还会归档留存，方便后续追溯。

3. 核心黑科技：Delta specs（增量规范）

这是OpenSpec最核心的设计，简单说就是只记录「变化的内容」，不用每次都修改整个项目的规范文档。 增量规范会明确标注出新增（ADDED）、修改（MODIFIED）、删除（REMOVED）的需求，AI只需要关注这些变化的部分，既减少了AI的上下文负担，也让开发者能快速看懂「这次要改什么」。比如给系统加双因素认证，只需要在增量规范里标注新增的认证需求，不用动原有登录逻辑的规范。

4. 全流程可追溯，支持项目审核与验证

开发过程中，你可以通过OpenSpec的CLI命令，随时查看、验证项目状态：

• 列出所有待实现的变更：openspec list
• 查看某个变更的详细内容：openspec show 变更名称
• 验证规范格式是否正确：openspec validate 变更名称
• 打开交互式面板查看项目全貌：openspec view

所有变更完成归档后，会自动移到changes/archive/目录，记录下每次修改的时间、内容，形成完整的审计记录，团队协作时，谁改了什么、为什么改，一目了然。

三、5分钟快速上手，手把手教你用OpenSpec做开发

说了这么多，最关键的还是实际操作，接下来以「给应用添加暗黑模式」为例，手把手教你走完OpenSpec的完整开发流程，全程简单易操作，新手也能快速掌握。

第一步：安装并初始化OpenSpec

1. 安装前提

需要Node.js ≥20.19.0版本，先在终端验证版本：node --version。

2. 全局安装OpenSpec

推荐用npm安装，国内用户可以先设置淘宝镜像，速度更快：

# 国内用户先设置淘宝镜像（可选）
npm config set registry https://registry.npmmirror.com
# 全局安装OpenSpec
npm install -g @fission-ai/openspec@latest

3. 验证安装

终端输入：openspec --version，能显示版本号就是安装成功。

4. 项目初始化

进入你的项目根目录，执行：openspec init，自动生成上述的openspec/目录，初始化完成。

第二步：发起变更提案（propose）

这一步是告诉OpenSpec和AI「我要做什么」，终端输入命令，AI会自动生成该变更的所有结构化文档：

/opsx:propose add-dark-mode

执行后，AI会在openspec/changes/下创建add-dark-mode/文件夹，并自动生成4个核心文档：

• proposal.md：记录做这件事的原因、范围、整体方案。比如添加暗黑模式是因为用户反馈夜间使用眼疲劳，范围包括加主题开关、支持系统偏好、保存用户设置。
• specs/目录：增量规范，明确新增的「主题选择」需求，以及对应的使用场景（手动切换、系统偏好适配）。
• design.md：技术实现方案，比如用CSS自定义属性做主题、用React Context管理状态。
• tasks.md：分步骤的实现清单，带勾选框，比如「创建ThemeContext」「添加CSS主题变量」「制作主题切换按钮」等。

第三步：执行实现（apply）

确认提案和文档没问题后，让AI按照清单生成代码，终端输入：

/opsx:apply

AI会逐个完成tasks.md里的任务，每完成一项会自动标记，全程无需手动干预。如果开发过程中发现设计有问题，直接修改对应的design.md或proposal.md，AI会同步更新实现方案，非常灵活。

第四步：验证并归档（archive）

代码实现完成后，确认功能符合需求，执行归档命令：

/opsx:archive

这一步会完成两个核心操作：

1. 把add-dark-mode/里的增量规范，合并到项目的核心规范openspec/specs/中，让暗黑模式成为系统的正式功能；
2. 把add-dark-mode/文件夹移到changes/archive/中归档，生成带时间戳的文件夹，方便后续追溯。

至此，一个完整的功能开发就完成了，全程不用跟AI反复沟通需求，不用手动整理文档，既高效又规范。

写在最后

OpenSpec的出现，让AI编程从「模糊的对话式开发」变成了「精确的规范式开发」，它没有改变AI编程助手的使用方式，而是给AI编程加了一套「规矩」，让AI的能力能更高效、更稳定地发挥出来。

不管你是单兵作战的个人开发者，还是需要团队协作的技术负责人，亦或是开源项目维护者，OpenSpec都能帮你提升AI编程的效率，减少返工，降低开发成本。

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