OpenSpec（开放规格驱动开发）

定义

OpenSpec 是一套面向 AI 编程助手的轻量级规格驱动开发（SDD）框架——在让 AI 写代码之前，先用结构化的"变更（Change）"制品对齐需求与设计，再由 AI 按规格实现，最后归档变更、更新规格，形成"探索→提议→实现→归档"的闭环工作流。

它由 Fission-AI 开源（@fission-ai/openspec），核心理念是：fluid not rigid（流畅而非僵化）、iterative not waterfall（迭代而非瀑布）、easy not complex（简单而非复杂）、built for brownfield（面向存量代码而非仅绿地）、scalable（从个人项目到企业可扩展）。

与 Spec-Driven Development 的关系：OpenSpec 是 SDD 的一种具体落地工具与工作流，把"先写规格再实现"固化为可执行的 slash 命令与目录约定，降低 SDD 的上手门槛。与 Spec Kit（GitHub）相比更轻量、无刚性阶段门；与 Kiro（AWS）相比不锁定 IDE 与模型。

核心特点

1. 变更即制品：每个功能/改动对应一个独立目录，含 proposal.md（为什么做）、specs/（需求与场景）、design.md（技术方案）、tasks.md（实现清单），人机共同维护。
2. 探索先行：/opsx:explore 作为"无 stakes 思考伙伴"，先读代码、权衡方案、成形计划，再决定是否提议，避免"上来就写"。
3. 制品引导工作流：explore → propose → apply → archive 四步闭环，每步产出可评审的制品，而非自由对话。
4. 流畅可迭代：任何制品随时可改，无刚性阶段门（phase gate），适配敏捷与探索式开发。
5. 工具无关：通过 slash 命令集成 25+ AI 助手（Claude Code、Cursor、Codex、Gemini CLI、Copilot 等），不锁定单一工具。
6. 棕地友好：专为存量代码库设计，支持在已有项目上渐进式引入规格层。
7. 规格即活文档：归档时更新 specs/，规格随代码演进，避免文档腐烂。

工作流程

flowchart TD
    A[模糊想法/需求] --> B["/opsx:explore 探索"]
    B --> C[AI 读代码 + 权衡方案 + 成形计划]
    C --> D{是否值得做?}
    D -- 否 --> Z[结束/重新探索]
    D -- 是 --> E["/opsx:propose 提议"]
    E --> F[生成 changes/功能名/ 目录]
    F --> G["proposal.md + specs/ + design.md + tasks.md"]
    G --> H[人评审制品]
    H -- 修改 --> E
    H -- 通过 --> I["/opsx:apply 实现"]
    I --> J[AI 按 tasks.md 逐项实现]
    J --> K[全部任务完成]
    K --> L["/opsx:archive 归档"]
    L --> M[归档到 archive/ + 更新 specs/]
    M --> N[规格成为活文档, 准备下一个变更]

命令参考

OpenSpec 有两类命令：终端命令（在 shell 中执行 openspec ...）与 slash 命令（在 AI 助手聊天中输入 /opsx:...）。两者混淆是最常见的入门坑——openspec init 在终端跑，/opsx:propose 在聊天框输入。

终端命令（CLI）

Slash 命令 — 核心集（core profile，默认装）

推荐节奏：explore → propose → apply → archive。/opsx:sync 多数情况由 archive 自动处理，不必手动跑。

Slash 命令 — 扩展集（expanded profile，需 openspec config profile 切换后 openspec update）

不同 Agent 的语法差异

不确定时，在 AI 聊天里输入 / 看自动补全。

变更目录结构

openspec/
  changes/
    add-dark-mode/          # 进行中的变更
      proposal.md           # 为什么做、改什么
      specs/                # 需求与场景（验收依据）
      design.md             # 技术方案
      tasks.md              # 实现清单（AI 按此执行）
    archive/
      2025-01-23-add-dark-mode/   # 已归档的变更
  specs/                    # 当前规格（活文档，随归档更新）

新项目从零接入

OpenSpec 是"CLI 在终端、slash 在聊天"的双层架构。新项目接入只需两步终端命令 + 一次 AI 对话验证：

# 1. 全局安装 CLI（任选其一）
npm install -g @fission-ai/openspec@latest
# 或: pnpm add -g @fission-ai/openspec@latest
# 或: yarn global add @fission-ai/openspec
# 或: bun add -g @fission-ai/openspec

# 2. 进入项目目录初始化
cd your-project
openspec init

openspec init 会做三件事：

1. 创建 openspec/ 目录骨架（changes/、specs/、archive/、config.yaml）。
2. 检测你用的 AI 助手（Claude Code / Cursor / Windsurf / Copilot 等），把对应语法的 slash 命令文件写进各自的配置目录。
3. 询问是否启用 expanded profile（含 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify 等），默认 core。

初始化完成后重启 AI 助手，在聊天框输入 / 应能看到 /opsx:explore、/opsx:propose 等补全——这就是装好了。验证最稳的方式是跑一次 /opsx:onboard（需 expanded profile），它会在你的真实代码上走完一个完整变更并逐步解说。

命令文件丢失、或切换 profile 后跑 openspec update 重新生成；想换命令集跑 openspec config profile 再 openspec update。

存量项目（棕地）也用同一流程，无需重构——OpenSpec 是"为已有代码库加规格层"，不是"为规格层重写代码"。

优缺点

优点

• 可预测性：人机在写代码前对齐规格，减少"形似而神不至"的 AI 产出。
• 轻量上手：相比 Spec Kit 的重型阶段门，OpenSpec 流畅可迭代，无 Python 环境负担。
• 工具无关：25+ AI 助手通用，不锁定 IDE/模型，团队可异构工具协作。
• 棕地友好：专为存量代码设计，可渐进式引入，无需重构整个项目。
• 活文档：归档即更新 specs，规格与代码同步，避免文档腐烂。
• 可追溯：每个变更独立目录，需求→规格→设计→任务→代码全链路可追。

缺点

• 仍需纪律：制品若不维护会腐烂，依赖团队坚持 explore→propose→apply→archive 闭环。
• 探索期可能过重：极小改动走完整流程略显仪式感，需判断何时跳过 explore。
• 依赖高推理模型：官方推荐 Codex 5.5 / Opus 4.7 等高推理模型，弱模型产出质量不稳定。
• 上下文卫生要求：实现前需清理上下文窗口，上下文混乱会影响规格对齐质量。
• 学习曲线：制品结构与命令体系需团队统一培训。

实战示例

场景：为现有项目加暗色模式。

You: /opsx:explore
AI:  让我看看你的样式方案……
     最干净路径：CSS 变量 + 小型 theme context + 系统偏好检测，
     无需新依赖。要限定范围吗？
You: 是，就这么做。

You: /opsx:propose add-dark-mode
AI:  已创建 openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做、改什么
     ✓ specs/       — 需求与场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现清单
     可以实现了！

You: /opsx:apply
AI:  正在实现任务……
     ✓ 1.1 添加 theme context provider
     ✓ 1.2 创建切换组件
     ✓ 2.1 添加 CSS 变量
     ✓ 2.2 接入 localStorage
     全部任务完成！

You: /opsx:archive
AI:  已归档到 openspec/changes/archive/2025-01-23-add-dark-mode/
     规格已更新。准备下一个变更。

完整接单流程：从一个需求到归档

下面以"客户要求给一个已有 Vue 项目加导出 PDF 功能"为例，把从接单到归档的完整操作列出来。前提：项目已 openspec init 完成（见上文「新项目从零接入」）。

几个关键纪律：

• 步骤 5 是质量门：propose 之后一定要人工评审，别直接 apply——AI 起草的 specs 经常漏边界场景。
• 步骤 7 前清上下文：apply 前新开会话或清理历史，避免探索期的对话污染规格对齐。
• 步骤 8 可选但推荐：/opsx:verify 不阻塞归档，但能提前抓到"AI 声称完成实则没实现"的问题。
• 步骤 10 别忘合并 specs：archive 不只是移动文件夹，关键是把 delta 合并进主 specs/——否则活文档会脱节，下一个变更就没了基础。
• 判断粒度：客户要改个按钮颜色，不必走完整 11 步，直接改 + 跑测试即可；中等以上改动才启用完整流程。

接下一个单子时，从步骤 1 重新开始——openspec/specs/ 已经积累上一次的活文档，下一次的 explore 会基于更准确的现状。

注意事项

1. 判断流程粒度：小修小补可直接改，不必走完整 explore→propose；中等以上改动才启用完整流程。
2. 探索是低成本的：explore 不产生变更目录，是"无 stakes"的思考伙伴，多用探索降低后期返工。
3. 制品要评审：propose 后务必人工评审 proposal/specs/design/tasks，不要直接 apply——评审是质量门。
4. 保持上下文卫生：实现前清理上下文窗口，避免历史对话污染规格对齐。
5. 选对模型：规划与实现都用高推理模型（Codex 5.5 / Opus 4.7），弱模型易偏离规格。
6. 归档即更新 specs：archive 时务必让 AI 更新 specs/，否则活文档会脱节。
7. 棕地渐进引入：存量项目可先对核心模块引入 OpenSpec，不必一次性覆盖全库。
8. profile 选择：默认 profile 含 explore/propose/apply/archive；需要 new/continue/verify 等扩展命令时用 openspec config profile 切换。

与相邻范式的关系

参考资料

• OpenSpec 官方仓库：https://github.com/Fission-AI/OpenSpec
• OpenSpec 文档首页：https://github.com/Fission-AI/OpenSpec/blob/main/docs/README.md
• Explore First 指南：https://github.com/Fission-AI/OpenSpec/blob/main/docs/explore.md
• 命令工作原理：https://github.com/Fission-AI/OpenSpec/blob/main/docs/how-commands-work.md
• 官网：https://openspec.dev/

FAQ

• 问题 1：OpenSpec AI 开发是否必须要有基线文档（baseline spec）

  • 结论：流程规范上必须存在基线，但不要求一次性写完整基线，分新项目 / 存量项目两种场景
  • 底层逻辑：基线 specs 是 OpenSpec 唯一事实源（source of truth） OpenSpec 的 SDD（规范驱动开发）核心规则：所有 AI 编码、评审、测试只能以openspec/specs/下的基线规范为依据；无基线则 AI 没有统一约束，会回到无规范的自由编码（vibe coding），框架校验、delta 增量、归档机制全部失效。 官方流程强制要求：编码前必须有可读取的基线规范，AI 编码入口会锁定，缺失基线无法执行opsx:apply生成代码。 不用一次性产出完整全量基线（适配存量老项目） OpenSpec 设计了Delta Spec 增量机制，不需要先梳理完整个系统再使用： 新项目：初始化时直接编写完整模块基线； 存量项目：可先用openspec reverse逆向代码生成极简粗糙基线（哪怕仅一段模块描述）作为起点，后续每次迭代通过变更 delta 持续补全、完善基线，逐步收敛完整。
  • 补充：基线≠不能变更，每次功能迭代生成changes/增量文档，完成后执行openspec archive把 delta 合并进基线，持续更新基准。

• 问题 2：文档是否必须连续性；团队不全使用 OpenSpec 的风险

  • 2.1 文档连续性要求：业务 + 技术规范必须全局连续、可追溯 机制层面天然要求连续闭环 OpenSpec 采用「基线 spec + 增量变更 delta」链式结构： 基线记录系统当前稳态； 每次变更的 proposal/design/tasks 是对基线的增量修改； 归档后增量合并入基线，形成完整变更历史链； 如果文档断裂（缺失历史变更、delta 不合并、旧 spec 不更新），会出现规范与代码漂移：AI 读取基线时获取过时规则，生成代码和线上逻辑不一致，verify校验直接报 CRITICAL 严重错误。 允许的局部 “不连续”：仅临时explore讨论（不落地编码）可无完整链路，正式开发流程不允许断裂。
  • 2.2 团队不全用 OpenSpec，存在明确负面影响，分轻重： 负面影响 1：双事实源，规范彻底失效 部分人走 OpenSpec 流程（产出标准化 spec），部分人直接写代码 / 用普通 AI 对话，会出现两套标准：代码实现和基线 spec 不同步，AI 校验、自动化测试全部失效，失去 SDD 核心价值。 负面影响 2：大量手动同步成本 不用 OpenSpec 的成员产出需求 / 方案无法自动生成 delta，使用者需要人工把零散文档翻译成标准 spec、手动合并基线，流程负担翻倍，极易遗漏变更点。 负面影响 3：新人、AI 上下文混乱 AI 读取代码库时，同时看到标准化 spec 和无规范的零散注释 / 聊天记录，产生逻辑冲突，代码生成幻觉、返工率大幅上升。 缓解方案（无法根除，仅降低风险） 强制 Git 钩子：所有代码变更必须配套 OpenSpec delta 文档，否则禁止提交； 统一事实源：所有需求、方案统一写入 spec，临时聊天记录仅作辅助，不纳入开发依据； 定时批量归档：每周执行一次基线同步，补齐非 OpenSpec 流程产生的变更。

• 问题 3：是否会极大增加 token 开销

  • 结论：不会极大增加，长期反而显著降低总 token 消耗；仅单次规划阶段小幅增量，有机制控制膨胀 短期小幅增量：规划阶段（propose）需要读写 spec、proposal、design，相比直接对话编码，单次请求输入 token 会少量上涨（10%~30%），属于一次性规划成本。 长期大幅节省（核心优势） 普通自由编码：AI 反复模糊对齐需求、多轮纠错、重写代码，大量 token 浪费在沟通澄清、返工； OpenSpec：规范一次性对齐需求，AI 仅读取结构化明确约束，减少多轮来回沟通；行业实测同等功能总 token 降低 30%~50%，返工减少 60% 以上。 内置控 token 机制，避免无限膨胀 规划与编码会话隔离：把写 spec、生成代码拆为两次独立 AI 调用，不把全部历史对话塞进同一上下文； archive 归档清理：完成迭代后归档增量，旧变更文档移出主上下文，AI 只加载当前有效基线，不会累积海量历史文档； Delta 增量设计：每次变更仅传递改动片段，不需要加载完整系统基线，避免全量长文本输入消耗 token。 对比同类 AI 开发框架：OpenSpec 属于轻量 spec 方案，token 消耗远低于 BMAD、全 Agent 链式开发框架，几乎无额外长期成本。