OpenSpec 上手：面向 AI Coding 开发者的 OPSX 工作流全指南

一、你有没有遇到过这种崩溃时刻

上午跟 AI 聊了半小时需求，中午让它写代码，下午发现它记岔了一半；同事接手你的仓库，翻遍聊天记录也搞不清"为什么这里要这么写"；同一个团队，两个人各自和 AI 对话，两周后代码风格分成了两派。

AI 编码时代最贵的成本，不是生成，而是返工。 而返工的根，几乎都在"没约定"三个字。

这就是 OpenSpec 要治的病——一个由 Fission-AI 开源的轻量规范驱动开发（SDD）框架，专门面向 AI 编码协作。本文写给正在用 Cursor、Claude Code、Copilot 的开发者，读完你会知道要不要给自己的项目也接一个。

二、AI 编码到底在痛什么

原生 AI 编码就是靠"聊天窗口"传递需求，几个老毛病绕不开：

• • 需求只存在聊天里，一关窗口就丢
• • 无文档追溯，一个月后回来自己都看不懂
• • 跨仓库难统一，多项目共用一套标准全靠人肉记
• • 团队规范漂移，每个人和 AI 对话的口径都不一样
• • AI 实现偏离预期，写完才发现要返工

OpenSpec 的思路很直接：在代码和需求之间塞一层可版本化、可审阅的规范，让人和 AI 先对齐、再动手。OPSX 就是要治这个。

三、核心思想：先约定，后编码

一句话概括——先约定，后编码。

写代码前，你和 AI 一起把需求、规范、任务清单落成 Markdown 文件；写完之后，AI 自己拿这份约定校验代码是否走样；变更做完，规范沉淀到主库，下一个功能继续复用。

你可以把它理解为给 AI 一份可版本化的合同：合同白纸黑字，履约与否肉眼可查，出错也知道追哪一行。

四、四个必须先搞懂的概念

• • 变更（Change）：一次独立的开发任务，放在 openspec/changes/ 目录下，一次需求一个文件夹。
• • 工件（Artifact）：变更全流程的产出物——提案 proposal.md、规范 specs/、设计 design.md、任务清单 tasks.md。artifact 之间有依赖关系，构成一张 DAG——细节看下一节。
• • 规范（Specs）：项目全局或模块的通用设计约定，存 openspec/specs/，可被多个变更共享。
• • 同步与归档：变更做完，规范可以先 sync 合并进主库，再 archive 封存整个变更。

五、OPSX：不是阶段，是动作

真正让 OpenSpec 值得从旧工作流迁过来的，是它的新招牌——OPSX。

一句话通俗定义：动作 = 你在做的事情（提案、写代码、修订、归档），而不是流程里非走不可的一个格子。

这三条是 OPSX 的核心主张：

• • 你能任意顺序、任意时机组合动作——写了一半 apply 发现设计不对？回头 update 一下再继续，不用推倒重来。
• • dependencies 是 enabler 不是 gate——依赖告诉你"下一步可以做什么"，而不是"这一步没做完你不许动别的"。
• • Legacy 旧工作流的 phase-lock 被 OPSX 显式取代——过去必须走"规划 → 实施 → 归档"三段闸门，现在闸门拆了。

DAG + 三态：为什么可以自由跳跃

底下的机制其实很简单——artifact 之间是一张有向无环图（DAG），每个 artifact 有三态：

BLOCKED ──► READY ──► DONE
  │           │         │
缺依赖      依赖齐备   文件已存在

proposal → specs → design → tasks 的依赖关系决定谁能做，状态由"这个文件在磁盘上有没有"决定——不是由"你走到哪个阶段"决定。所以你 update 一下 design.md，tasks.md 不会因此被强制重跑；apply 到一半改了 specs，next apply 自动往前走。

Legacy vs OPSX 一张表看清

工作本来就不是线性的。OPSX 只是不再假装它是。

六、命令速查（核心 6 + 扩展 6）

核心命令（默认 profile 就有，装完 openspec init 到手）：

扩展命令（需要跑 openspec config profile 切到 Expanded、再 openspec update 才会出现）：

命令数量以你本机 .claude/commands/opsx/ 为准——文档说的和你机器上的可能不完全一样。

七、两种典型落地场景

场景一：需求还没吃透

假设你要给系统加一套 OAuth 登录，思路还朦胧。先 /opsx:explore 和 AI 掰扯技术选型和边界；方向定了直接 /opsx:propose "接入 OAuth 登录"，四份工件一次生成。翻一遍不满意？/opsx:update 局部修订。规划稳了 → /opsx:apply 出代码。写代码时发现 design 有漏？停下 /opsx:update 改完 design，再 /opsx:apply 继续。全部做完 → /opsx:sync 沉淀通用规范 → /opsx:archive 归档收工。每一步都能刹车、能回头，风险收敛。

场景二：需求很明确

只是加个导出 CSV 按钮？跳过 explore，直接 /opsx:propose "在设置页加导出 CSV 按钮" → /opsx:apply → /opsx:archive。三条命令走完一个功能。

八、团队协作：靠 Stores 跨仓库共享规范

个人用 OpenSpec 能防遗忘；到了团队，真正的大杀器是 Stores（Beta）——把全局规范单独放一个仓库，让多个代码仓库共用一套需求标准。

• • 平台团队维护只读共享规范，业务团队直接引用，杜绝 Wiki 文档漂移
• • 跨仓库功能可以在一份变更里统一规划，覆盖多项目代码
• • 支持先规划规范、后落地代码，适配前置规划场景

一句话：代码是规范的落地产物，不是反过来。

Stores 是 Beta 能力，和本文重点讲的 OPSX 是两条正交的路径——不用 OPSX 也能用 Stores，反之亦然。

九、OpenSpec 与同类怎么选

vs GitHub Spec Kit：Spec Kit 重、流程僵化、依赖 Python；OpenSpec 轻量化，迭代灵活，无强制阶段锁。

vs AWS Kiro：Kiro 绑定专属 IDE、仅支持 Claude；OpenSpec 工具中立，兼容 Cursor / Claude Code / Copilot / Codex / Gemini CLI 等 25+ 主流 AI 编码助手。

vs 无规范原生 AI 开发：消除模糊对话带来的不可控输出，全流程可追溯、可评审、可沉淀。

十、Project Config：让 AI 一次就懂你的项目

每个新 change 都要重新告诉 AI 一遍技术栈、代码风格、测试框架？累不累？更糟的是——每次口径都会飘一点，一个月后同一个仓库里两份 spec 用的是两套术语。

OpenSpec 提供一个项目级配置文件openspec/config.yaml，把项目上下文一次写好，自动注入所有 artifact instructions——AI 起草每一份 proposal / specs / design / tasks 时都能读到，语义先对齐再动笔。

openspec init 时会问你要不要建，也可以随时手写。最小示例：

schema: spec-driven

context: |
  技术栈：TypeScript、React、Node.js
  接口约定：RESTful，JSON 响应
  测试：Vitest 跑单测，Playwright 跑 e2e
  代码风格：ESLint + Prettier，strict TypeScript

rules:
  proposal:
    - 必须包含回滚方案
    - 标注受影响的团队
  specs:
    - Scenario 用 Given/When/Then 格式

两个字段各司其职：context 一次注入所有 artifact，跟每一份文档都相关的通用背景放这里；rules 按 artifact 分别注入，key 就是 artifact ID（proposal / specs / design / tasks），每种工件独有的硬性约束单独列。

复制粘贴，改成你自己的。 从此 AI 起草文档时，你的团队规矩它先看一遍——比在每次对话开头贴一遍上下文靠谱得多。

十一、三步上手

要求 Node.js 20.19.0+，全局 CLI 一键装完。

# 1. 安装
npm install -g @fission-ai/openspec@latest

# 2. 项目根目录初始化
openspec init

# 3. 挑一个入口
#    需求模糊 → /opsx:explore
#    需求清楚 → /opsx:propose "你的一句话需求"

想看全局面板，跑 openspec view，终端里就是一块仪表盘：规范总量、进行中/已完成变更、任务完成进度一目了然。

十二、常见问题

Q1：斜杠命令在编辑器里不显示？ A：跑 openspec update 刷指令，重启 Cursor / VS Code，确认项目根有 openspec/ 目录，确认用的是支持斜杠命令的 AI 工具。

Q2：规划做到一半发现方向偏了？ A：用 /opsx:update 局部修订 proposal / design / specs / tasks，保持工件之间一致，不用推倒重来。

Q3：sync 和 archive 有啥区别？ A：sync 只合并规范，变更本身还活跃；archive 归档前会自动跑一次 sync，然后封存变更。

Q4：我本机 opsx 命令数量跟文档不一致怎么办？ A：一切以你本机 .claude/commands/opsx/ 里真实存在的文件为准。想开更多扩展命令：跑 openspec config profile 切 profile，再 openspec update 刷新。

Q5：Custom Schemas 是啥？我要不要用？ A：不需要立刻用。默认 spec-driven 已经够跑日常项目。有特殊工作流（比如想在 proposal 前多一个 research 工件）再用：openspec schema fork spec-driven my-workflow 起个模板改。

十三、什么时候续做，什么时候新开一个 change

你不做 SDD 也可以读这段——它其实是软件迭代的普适判断力。

两条清晰的分叉线索：

• • 同一 intent，精修执行 → update：范围收窄、边缘 case 冒出来、发现小设计偏差——都还是"同一件事"。例：Add dark mode → Add dark mode toggle。
• • intent 已变，或范围爆炸 → 新开：问题本身变了、改到一半发现原提案面目全非、原 change 已经能独立"完成"。例：Add dark mode → Add comprehensive theme system with custom colors, fonts, spacing。

判断难时问自己三个问题：同一个问题吗？scope 重叠超 50% 吗？原 change 不做这些改动能不能"完成"？——三个都倾向 YES 就 update，反之新开。

一句金句：Update 保留上下文，New 提供清晰度。 想留思考链就 update，重新出发更清楚就新开。

十四、结语

编者按：把 OpenSpec 装进一个存量项目最直接的收益，不是马上快多少，而是——你终于能对着仓库、而不是聊天记录，回答"这个功能当初为什么这样设计"。当 AI 越来越会写代码，懂得给它立规矩的开发者才是稀缺资源。

下一个功能，别急着让 AI 开工。先 /opsx:explore 聊聊，或者直接 /opsx:propose 起一份提案——先签约，再写代码。

今天的分享就到这里。后续我会持续为大家带来实用的技术干货和前沿的技术资讯。