跳至主要内容

OpenSpec：比 Spec Kit 更轻的规格驱动开发，专为存量项目设计

Fen9Pi2026/9/8方法论方法论大约 7 分钟

前言

上一期写了 GitHub 官方的 Spec Kit，有读者问：有没有更轻的选择？ " 有。OpenSpec，Fission-AI 出的开源规格驱动工具，和 Spec Kit 解决同一个问题——AI 编码前先对齐"要建什么"——但路数明显不同。

它的哲学写在 README 开头，五句话：

流动不僵化、迭代不瀑布、简单不复杂、为存量项目而生、从个人项目到企业都能伸缩。

最后一句最扎眼。大部分规格驱动工具默认你从零开始建新项目，但现实世界的代码库几乎全是存量项目（brownfield）——OpenSpec 把这个当成了第一设计目标。

一句话说清楚：

在写任何代码之前，人和 AI 先就规格达成一致；每个变更一个文件夹，随时改，没有阶段门。

  • GitHub：https://github.com/Fission-AI/OpenSpec
  • npm：@fission-ai/openspec，MIT 协议
  • 支持 30+ AI 编码工具

一、项目身份

OpenSpec 是一个轻量级规格层（spec layer），插在你的项目和 AI 助手之间。

它存在的理由很朴素：需求只存在于聊天记录里时，AI 编码助手强大但不可预测。上下文一长，聊天里的约定就稀释了；换个会话，AI 就忘了昨天说好的事。OpenSpec 把这些约定落到磁盘上的 Markdown 文件里，变成人和 AI 都能读、都能改、都能评审的事实源。

和同类工具的定位差异，官方自己说得毫不客气：

  • vs Spec Kit（GitHub）：认可它够彻底，但嫌它重——阶段门僵硬、Markdown 产出多、还要装 Python。OpenSpec 更轻，随时自由迭代
  • vs Kiro（AWS）：Kiro 强大但锁 IDE、限 Claude 模型。OpenSpec 用你手头已有的工具
  • vs 什么都不用：无规格的 AI 编码 = 模糊 prompt + 不可预测的结果。OpenSpec 给可预测性，不给你仪式感

一个细节证明它言行一致：OpenSpec 用 OpenSpec 开发。仓库里的 openspec/specs 和 openspec/changes 就是活的实例，规模不小，随时可以去看真实产出长什么样。

二、主执行链路

流程图1

四个命令走完全程， dark mode 这种小功能十分钟跑完：

  1. /opsx:explore（可选起点）：还没想清楚要建什么？这是个"零赌注"的思考伙伴——它读你的代码、比较方案权衡、在动任何代码前把计划塑形。官方演示里它甚至会建议"CSS 变量 + 小型 theme context 就够了，不需要新依赖"
  2. /opsx:propose：一个命令生成完整的变更文件夹——proposal（为什么、改什么）+ specs（需求场景）+ design（技术方案）+ tasks（清单）
  3. /opsx:apply：AI 按任务清单执行
  4. /opsx:archive：做完归档，同时把定稿的需求合并进 openspec/specs——这是项目的"当前能力"事实源，下个变更从这里出发

人工评审卡在写代码之前。AI 写规格，你审规格，代码只在确认后才生成。这是"agree before you build"的字面执行。

没有阶段门是它和 Spec Kit 最本质的区别。四个产物放在同一个文件夹里，哪个没定稿就先改哪个，随时回头，不会流程卡你。默认装 explore + propose + apply + archive 四个命令，想要进阶工作流（/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard）用 openspec config profile 选配。

三、核心模块与架构

流程图2

两个目录撑起整个模型：

  • openspec/specs/——项目现在的样子。每个已交付能力的规格都在这
  • openspec/changes/——项目正在变成的样子。每个进行中的变更一个独立文件夹，四件套齐全

这个"specs vs changes"的二分法是 OpenSpec 的核心心智模型：规格不是一次性文档，而是随归档不断进化的事实现场。

规格长什么样？纯 Markdown，没有要学的特殊语法：

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

SHALL/WHEN/THEN 这种结构化句式保留了验证的可判定性，但载体就是普通 Markdown——AI 写，人审，git diff 能看。

四、跨端边界

  • 工具支持：30+ AI 工具，命令形态自适应——Claude Code 用 /opsx:propose，Cursor 和 GitHub Copilot 是 /opsx-propose，Amazon Q 是 @opsx-propose，Codex 是 $openspec-propose。openspec init 会直接打印你选的工具该用哪种写法
  • 包管理器：npm 装，pnpm/yarn/bun/nix 都行，只要 Node ≥ 20.19.0
  • 安装方式的姿态：可以直接把官方 setup prompt 粘给 AI 助手，让它自己装 CLI、跑 init、验证结果——连安装都可以是 AI 干的

五、数据与状态流

流程图3

状态流的核心是归档即合并：变更文件夹里的 ADDED/MODIFIED Requirements 在 archive 时合并进主 specs，规格库随开发持续演化。

人工编辑有专门的处理路径。文档里有单独一章讲"Editing a Change"——更新产物、回退、协调手改。规格层承认人是会动手改文件的，不把这事当异常。

Stores 是最值得盯的动向（beta）：把 openspec/ 形态放进一个独立的规划仓库，git push 共享。解决的是团队场景的三个真痛点：

  1. 跨仓库功能——一个变更一份计划，哪怕代码落进三个仓库
  2. 共享需求——平台团队拥有规格，产品团队只读引用，AI 助手直接读，不再有漂移的 wiki
  3. 先于代码规划——计划先进 store，代码仓库随后跟上

单人单仓库，OpenSpec 让你和 AI 互相诚实；多人多仓库，Stores 让整个组织和所有 Agent 读同一份真相。

六、配置边界

配置面很克制：

  • 初始化：openspec init 选工具、生成 Agent 指令文件
  • 工作流档位：openspec config profile 切默认/进阶命令集，openspec update 应用
  • 更新：升级包 + 每个项目跑一次 openspec update 刷新指令
  • 遥测：匿名收集，只有命令名和版本，CI 自动关闭，OPENSPEC_TELEMETRY=0 或 DO_NOT_TRACK=1 关掉

没有数据库，没有服务端，没有账号体系。openspec/ 文件夹就是全部状态。

七、扩展点

  • 社区 schemas：第三方 schema 包，独立仓库分发，提供带主张的工作流集成——官方直接拿 spec-kit 的社区扩展目录当类比。定制文档里有目录入口
  • 自定义：定制文档覆盖工作流、模板的个性化改造
  • 贡献规则明确：小修直接 PR；大改动必须先提交 OpenSpec 变更提案——用它自己的流程管它自己的开发。AI 生成的代码欢迎，但要求标注用的什么 Agent 和模型（如"Generated with Claude Code using claude-opus-4.5"）

八、风险点

1. 轻是有代价的。没有 Spec Kit 的 constitution（项目宪法）、analyze（跨产物一致性）、checklist（需求质量测试）这些质量机制，也没有 converge 那样的显式对账循环。功能多、周期长的项目，少了这些闸门，漂移风险自己扛。

2. "随时可改"依赖自律。没有阶段门意味着没有强制评审点。人的自律不够时，"流动"很容易滑向"随便"——proposal 没写清楚就 apply，和不用规格工具的区别就不大了。

3. Stores 还在 beta。跨仓库规划是团队场景的真需求，但 beta 功能别押重注，生产关键流程先等等。

4. 依赖强推理模型。官方明说建议用高推理模型做规划和实现，还提醒注意上下文卫生。模型能力不够时，写出来的规格质量会成为瓶颈。

5. 归档合并是单点。specs 的准确性全靠 archive 环节的合并质量，没人认真做归档，规格库会逐渐和代码库脱节——那就退化成了一"份会过期的 wiki"，正是它想替代的东西。

记住

AI 编码助手在需求只活在聊天记录里时，强大但不可预测。

OpenSpec 的答案：写代码之前，人和 AI 先就规格达成一致——纯 Markdown、每个变更一个文件夹、随时改、没有阶段门。

规格不是文档，是随每次归档不断进化的事实现场。

参考资源

  • GitHub：https://github.com/Fission-AI/OpenSpec
  • 安装：npm install -g @fission-ai/openspec
  • 文档：仓库 docs/ 目录，Getting Started 起步
  • License：MIT
最近更新:
贡献者: Fen9Pi
Copyright © 2016-2022 风派 | 苏ICP备2025227748号-3