AI 编码工具越来越像一个“高产、聪明、执行力很强，但偶尔也会自作主张的新同事”。

你让它写个功能，它往往真能写出来；
但写出来的东西是不是你真正要的、边界是不是清楚、设计是不是一致、后续是不是好维护，就不一定了。

很多团队已经感受到一种很现实的落差：

不是 AI 不会写代码，
而是 AI 太容易在需求还没对齐时，就把代码写得飞起。

于是，问题开始从“怎么让 AI 写得更快”，转向“怎么让 AI 写得更准、更稳、更可追溯”。

这正是 OpenSpec 的价值所在。

它不是再造一个 AI，也不是替代 Claude Code。更准确地说，OpenSpec 是一套面向 AI 编码助手的规范驱动开发工作流；Claude Code 则是把这套工作流真正执行起来的强执行代理。

一个更像“方向盘”，一个更像“发动机”。

放在一起用，目标不是让 AI 写更多代码，而是让 AI 少写那些方向看似对、其实需求没对齐的代码。

先给结论：
如果你只是想让 AI 帮你“写一段代码”，OpenSpec 可能显得有点正式；
但如果你已经开始用 Claude Code 做真实项目、改现有代码库、推进多人协作任务，那 OpenSpec 往往不是“锦上添花”，而是“避免反复返工”的那层护栏。

这篇文章适合谁看

这篇文章尤其适合下面几类人：

• 已经在用 Claude Code、Cursor、Windsurf 之类 AI 编码工具的人；
• 经常做真实项目改造，而不是只写 demo 的开发者；
• 想把“聊天式开发”升级成“有留痕、有规范、有归档”的团队负责人；
• 看过一些 OpenSpec 教程，但被旧命令、旧流程、旧截图绕晕过的人。

读完你能得到什么

这篇文章会尽量回答 5 个最现实的问题：

1. OpenSpec 到底解决什么问题？
2. 它和 Claude Code 为什么适合一起用？
3. OpenSpec 1.2.0 之后，命令和工作流到底怎么理解？
4. 不同场景下，应该怎么走 propose / explore / apply / archive？
5. 团队如果想低成本落地，最小实践方案该怎么搭？

你不需要先接受一整套“新方法论”，再决定要不要用它。
更实际的方式是：先把文章读完，看看它能不能帮你解决下面这些老问题——

• AI 总是抢跑，需求还没对齐就开始写代码；
• 功能确实做出来了，但设计决策留不下来；
• 聊天里讲过的约束，过几天就没人记得；
• 一旦多人并行或者跨会话继续，整个上下文就开始漂移。

如果这些问题你都遇到过，那 OpenSpec 大概率值得认真看一遍。

---

一、先说人话：OpenSpec 到底是什么

一句话解释：

OpenSpec 是一套把“需求、规格、设计、任务、实现、归档”串起来的 AI 协作工作流。

它强调的不是“想到什么就直接让 AI 开始改”，而是：

1. 先把这次变更说清楚；
2. 再把系统行为和边界写清楚；
3. 必要时把技术方案定清楚；
4. 再把任务拆成可执行清单；
5. 最后才让 AI 进入实施阶段。

这套思路，本质上就是 Spec-Driven Development（规范驱动开发） 在 AI 编程时代的落地版本。

OpenSpec 的核心价值，不是多几个命令，而是把原本散落在聊天记录里的“共识”，沉淀成项目里的正式工件。这样一来，AI 的上下文不再只依赖会话记忆，而是开始依赖项目内可追踪、可审查、可归档的事实。

换句话说：

• 没有 OpenSpec 时，很多需求只存在于聊天里；
• 有了 OpenSpec 后，需求、设计和任务会变成项目内的正式资产。

这件事对个人开发者有帮助，对团队协作更重要。

因为团队最怕的不是 AI 写得慢，而是：

• 每个人都在用 AI，但每个人理解的范围不一样；
• 每个人都在提效，但结果不可复盘、不可审计、不可继承；
• 过几天回头看，只记得“改过”，却说不清“为什么这么改”。

OpenSpec 的意义，就是尽量把这种“聊天式开发”升级为“带工件留痕的工程式开发”。

---

二、为什么它和 Claude Code 很搭

Claude Code 的强项很明显：

• 能读取真实代码库上下文；
• 能连续执行多步任务；
• 能跑命令、查文件、改代码、补测试；
• 对真实工程改造比只会“补全一段代码”的工具更有行动力。

但工具越强，越需要约束。

因为越能干的代理式工具，越容易在下面这些场景里“用力过猛”：

• 需求边界没说清，就开始大范围改动；
• 设计方案还没定，已经先把实现铺开；
• 聊天里说过的关键限制，没有被固化进项目；
• 多任务切换后，前一次变更的上下文被新的目标冲掉；
• 最终代码能跑，但没人说得清“为什么这么实现”。

Claude Code 负责把事推进下去，OpenSpec 负责把事定义清楚。

所以两者组合起来，比较接近一种更成熟的协作关系：

• Claude Code：偏执行，擅长“做”；
• OpenSpec：偏约束，擅长“先把该做什么说清楚”。

一个负责“干活”，一个负责“把活干明白”。

这也是为什么，OpenSpec 特别适合搭配 Claude Code 这类能真正落地执行的 AI 代理，而不是只停留在问答层面的助手。

---

三、OpenSpec 1.2.0 最值得先知道的变化

如果你看过较早期的教程，最容易踩坑的地方只有一个：

现在的 OpenSpec，命令体系和工作流已经不是早期那套“旧版 OpenSpec”了。

对 1.2.0 来说，最关键的变化主要有这几项。

1. 默认 profile 变成了 core

现在默认全局 profile 是 core，只包含 4 个核心工作流：

• propose
• explore
• apply
• archive

这意味着：你新装 OpenSpec 后，并不会默认看到所有扩展命令。

2. propose 成了新手最佳入口

1.2.0 新增了 Propose workflow。它可以一步生成完整的 change proposal、specs、design 和 tasks，不再要求你先 new 再 ff。

这对新手特别友好：

你不需要先理解整套工作流拓扑，先从一句需求出发，就能快速得到一套完整的规划工件。

3. openspec init 会自动识别已有 AI 工具目录

现在 openspec init 会扫描 .claude/、.cursor/ 等已有目录，并预选检测到的工具。

这看起来像小优化，但实际上很实用：

它让 OpenSpec 更像“装到现有项目里”，而不是“逼你重新建一个世界”。

4. 工作流从“阶段锁定”转成“行动驱动”

新版 OPSX 的核心思想可以概括成一句话：

Actions, not phases.

也就是：

• 重点不是强行卡死在某个阶段；
• 而是用一组动作，把需求澄清、工件生成、实施、验证、归档连接起来。

你仍然要讲顺序，但顺序不再僵硬到“一旦前进就不能回头”。

5. Delta Specs 的语义更清晰了

在规范同步这件事上，OpenSpec 不再是“把整份规格文件整体替换掉”，而是支持更语义化的 delta sections，例如：

• ADDED Requirements
• MODIFIED Requirements
• REMOVED Requirements
• RENAMED Requirements

这让规格变更更像“增量演进”，而不是“整份重写”。

---

四、先用人话理解 OpenSpec 的目录结构

OpenSpec 真正有价值的地方，不只是命令，而是它会把“这次变更的思考过程”落到项目目录里。

一个典型项目初始化后，核心目录大致如下：

openspec/
├── specs/
├── changes/
└── config.yaml

再展开一点看：

openspec/
├── specs/                    # 当前系统的正式规格（source of truth）
│   └── <domain>/
│       └── spec.md
├── changes/                  # 每次变更的工作区
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/
│           └── <domain>/
│               └── spec.md   # delta specs：本次变更影响什么
└── config.yaml               # 项目级配置（可选）

这套结构里，最重要的是两个目录：

1. specs/：系统现状的正式规格

这里更接近“当前事实”。

也就是说：

• 它描述的是系统现在应该怎么工作；
• 它不是临时讨论区；
• 它是项目未来回看时最接近“正式口径”的地方。

2. changes/：每次变更的工作区

这里更接近“这一次准备怎么改”。

每个 change 都有自己的 proposal、design、tasks 和 delta specs。等变更完成后，再归档并把 delta specs 合并回主 specs。

这意味着，团队以后回头看一个功能，不只是知道“代码改成这样了”，还知道：

• 为什么要改；
• 改动范围是什么；
• 关键设计决策是什么；
• 任务是怎么拆出来的；
• 最终是否已经归档。

对工程团队来说，这比把一切埋在聊天记录里靠谱得多。

---

五、OpenSpec 里的两层命令体系，别混了

很多人第一次上手会有一个典型困惑：

OpenSpec 到底有哪些命令？为什么有的是 openspec xxx，有的是 /opsx:xxx？

答案很简单：它本来就分两层。

第一层：CLI 命令

这是你在终端里敲的命令，偏“人类管理项目和配置”。

例如：

• openspec init
• openspec update
• openspec list
• openspec validate
• openspec archive
• openspec config profile

第二层：工作流命令

这是你在 Claude Code、Cursor、Windsurf 这类 AI 工具对话里调用的命令，偏“让 AI 进入具体工作流动作”。

例如：

• /opsx:propose
• /opsx:explore
• /opsx:apply
• /opsx:archive
• /opsx:new
• /opsx:continue
• /opsx:ff
• /opsx:verify
• /opsx:sync
• /opsx:bulk-archive
• /opsx:onboard

最通俗的理解方式：

• openspec ...：像在装工具、管配置、查状态；
• /opsx:...：像在让 AI 真正开始按流程办事。

---

六、先装起来：安装、初始化、升级

按照当前官方 Quick Start，OpenSpec 需要 Node.js 20.19.0 或更高版本。

基础安装流程如下：

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

如果你主要是给 Claude Code 用，也可以显式指定工具：

openspec init --tools claude

如果你希望一次配置多个工具：

openspec init --tools claude,cursor

如果是自动化或无交互初始化，也可以用：

openspec init --force

初始化后会创建什么

openspec init 主要会创建两部分：

1. 项目内的 openspec/ 目录；
2. 针对所选 AI 工具生成的 skills / command 文件。

例如选择 Claude Code 时，通常会生成对应的 .claude/skills/ 内容。

升级后别忘了 openspec update

这是很多人会漏掉的一步。

当你升级 OpenSpec CLI 后，应该在项目里执行：

openspec update

它的作用不是“升级 npm 包”，而是重新生成项目里的指令文件和工作流配置，让当前项目和你现在的 profile / workflow 选择保持一致。

你可以把它理解为：

• npm install -g ...：更新工具本体；
• openspec update：把新规则同步到当前项目。

---

七、最常用的 CLI 命令表

很多人一上来最容易混淆的，就是“终端命令”和“对话里的工作流命令”。

这一节先把 CLI 层讲清楚：它主要负责安装、初始化、配置、检查、更新和归档等“项目管理动作”。你可以把它理解成 OpenSpec 的“系统层命令”。

下面这张表，重点讲终端里的 openspec 命令。适合放在文章里做“查阅型速览”。

1. CLI 核心命令总览

命令	主要作用	适合什么时候用	常见示例
openspec init	初始化项目，创建 openspec/ 结构并配置 AI 工具集成	第一次在某个项目接入 OpenSpec	openspec init --tools claude
openspec update	根据当前 profile / delivery 重新生成项目内指令文件	升级 CLI 后，或改了 profile 后	openspec update
openspec list	查看当前 change 或 specs 列表	想知道项目里有哪些活跃变更 / 规格	openspec list / openspec list --specs
openspec show <item>	读取指定 change 或 spec 内容	想快速看某个对象内容	openspec show add-dark-mode
openspec view	打开交互式 dashboard	想可视化浏览项目状态	openspec view
openspec validate	校验 change / spec 结构是否有问题	归档前、CI 校验、批量检查	openspec validate --all --strict
openspec archive	在 CLI 层归档已完成 change，并合并 specs	脚本化、终端化归档场景	openspec archive add-dark-mode --yes
openspec status	查看 artifact 进展状态	想知道某个 change 当前推进到哪	openspec status --json
openspec instructions	获取下一步建议或指令	给 agent / 脚本取下一步动作	openspec instructions --json
openspec templates	查看模板路径	团队准备自定义模板时	openspec templates --json
openspec schemas	查看可用 schema / 工作流支持	想了解有哪些 artifact workflow	openspec schemas
openspec config profile	配置 profile 和 workflow 选择	想从 core 切到扩展工作流时	openspec config profile
openspec config list	查看当前配置	排查为什么某些命令没出现	openspec config list

2. 你最可能用到的 CLI 命令详解

命令	关键参数 / 选项	解释	实战建议
openspec init [path]	--tools <list>、--force、--profile <profile>	初始化 OpenSpec，并为 выбран工具生成集成文件