OpenSpec 2.0 是什么:先写规格再让 Agent 写代码

OpenSpec 是一个开源命令行工具,在你和编程 Agent 之间加一层轻量规格:先在仓库里写清楚这次改什么、验收场景是什么,Agent 再动手写代码。MIT 许可,GitHub 74,822 星,npm 上周下载 124 万次。11 月 12 日发布的 2.0 把全部工作流改成 Agent Skill,统一装进 .agents/skills/。11 月 14 日我们对照 README、v2.0.0 发布页和官方文档整理了用法和升级要点。
它是什么
需求只活在聊天记录里,Agent 就容易照着它自己的理解开工。OpenSpec 的做法是把「要做什么」落成仓库里的文件,人和 Agent 都对着同一份规格干活,改完再把规格合并回主线。
| 仓库 | github.com/Fission-AI/OpenSpec |
|---|---|
| 作者 | Fission AI |
| 许可证 | MIT |
| 热度 | GitHub 74,822 星(GitHub API,2026-11-14 15:11 北京时间);npm 包 @fission-ai/openspec 上周下载 1,243,882 次(11-06 至 11-12) |
| 运行要求 | macOS / Linux / Windows;独立安装脚本免 Node,走 npm 需要 Node.js 22.12.0 以上;也支持 Homebrew、pnpm、yarn、bun、Nix |
| 最新版本 | v2.0.0(发布于 2026-11-12 06:41,北京时间) |
解决什么问题
官方写在 README 里的定位是「流动而非死板,迭代而非瀑布,为已有代码库设计」。落到文件上是这样一个结构:
openspec/
├── config.yaml 项目上下文和规则
├── specs/ 系统现在的行为(按领域分目录)
└── changes/
├── add-dark-mode/ 一次改动一个文件夹
│ ├── proposal.md 为什么做、范围
│ ├── specs/ 增量规格 ADDED / MODIFIED / REMOVED
│ ├── design.md 技术方案
│ └── tasks.md 带复选框的任务清单
└── archive/ 做完的改动归档到这里
增量规格(delta spec)是核心。每条需求用 SHALL / MUST 写,下面挂 GIVEN / WHEN / THEN 场景。归档时 ADDED 追加进主规格,MODIFIED 替换旧条目,REMOVED 删掉,change 文件夹搬进 archive/ 留档。几个月后再看 specs/,就是这个系统当前该有的行为,不用翻 PR 去猜。
和同类工具比,README 自己点了两个名字:
| 对比项 | OpenSpec | Spec Kit(GitHub) | Kiro(AWS) |
|---|---|---|---|
| 形态 | CLI + 一组 Skill | CLI + 模板,Python 环境 | 独立 IDE |
| 流程 | 文档随时可改,没有硬性阶段门 | 阶段分明,产出的 Markdown 多 | IDE 内置的规格流程 |
| 工具绑定 | 官方称支持 30 多种编程助手 | 多种 Agent | 只能在 Kiro 里用 |
| 适合 | 已有代码库上的增量改动 | 希望每一步都有固定阶段门的项目 | 已经在用 Kiro 的人 |
Spec Kit 的详细用法见我们之前的 Spec Kit 教程。上表 Spec Kit 和 Kiro 两列的说法出自 OpenSpec 的 README,是它自己的说法,选型时两边文档都翻一下。
怎么用
安装(macOS / Linux),或者用 npm:
curl -fsSL https://openspec.dev/cli/install.sh | sh
# 或
npm install -g @fission-ai/openspec@latest
在项目根目录初始化,--tools 可以跳过交互选择:
cd your-project
openspec init --tools claude,cursor
按官方文档,init 会创建 openspec/ 目录,并把 6 个默认 Skill 写进 .agents/skills/:explore、propose、apply-change、update-change、sync-specs、archive-change。Cursor、Codex 直接读这个目录;Claude Code、Kiro、通义灵码(Lingma)、CodeBuddy 等读自己目录的工具,会在 .claude/skills/ 这类位置拿到指向同一份文件的软链接。IDE 里的工具要重启一次才认得新 Skill。
之后就在 Agent 的对话框里推进:
/openspec-explore 想法还模糊时先聊,不写代码
/openspec-propose add-dark-mode 生成 proposal / specs / design / tasks
/openspec-apply-change 按 tasks.md 逐项实现
/openspec-archive-change 合并规格,归档改动
终端里有几条辅助命令:openspec list 看进行中的改动,openspec show add-dark-mode --diff 看需求差异,openspec validate 查格式,openspec view 是一屏总览。
团队规范别去改 Skill 文件,写进 openspec/config.yaml。context 每一步都会带上,rules 只在生成对应文档时生效,比如:
context: |
所有文档用中文写;设计必须覆盖 Windows 和 macOS
rules:
tasks:
- 每个任务以一次 commit 结束
官方提醒这里要写短,内容全会进 Agent 上下文,写长了效果反而变差。
2.0 升级要点
- Skill 只存一份:1.x 给每个工具各复制一套,2.0 统一放
.agents/skills/,其他目录用链接。 - 命令改名:
/opsx:propose→openspec-propose,/opsx:apply→openspec-apply-change,/opsx:archive→openspec-archive-change,12 个命令一一对应。也可以直接说「帮我提一个加暗色模式的改动」。 - 升级步骤:先 commit,更新 CLI,在每个项目跑
openspec update(可加--dry-run预览),再提交结果。重复运行不会再改东西。 - 两个坑:
update会重写.agents/skills/openspec-*,改过的内容直接被替换,只能从 git 找回,长期定制请另起一个不以openspec-开头的 Skill 名;Windows 队友要开git config --global core.symlinks true和开发者模式,否则链接会被检出成小文本文件。 - 移除:Amazon Q Developer 加载不了 Skill,2.0 不再支持,官方建议换 Kiro。暂时不想升,可以
npm install -g @fission-ai/openspec@1留在 1.x。
OpenSpec 只管动手之前这一步:改什么、怎么验收,先落成文件,代码还是 Agent 来写。
适合谁,不适合谁
适合:在已有代码库上让 Agent 做功能迭代、希望每次改动都留下需求记录的开发者;同一个仓库里有人用 Claude Code、有人用 Cursor 或 Codex,想共用一套流程的团队;嫌 Spec Kit 太重、又不想完全靠聊天的人。官方还在做 Stores(测试版),把规格放进单独仓库,给跨仓库的功能用。
不适合:改个文案、修个小 bug 这种一句话能说清的活,走一遍 propose 反而慢;README 写明它配高推理能力的模型效果最好,官方推荐的规划和实现模型都是各家旗舰款。
最后
挑一个手头正要做的小功能,在项目里跑 openspec init,用 /openspec-propose 生成计划,先只读 proposal 和 tasks 两份文件,看它对需求的理解和你的是否一致,再决定要不要让它开工。