OpenSpec 是什么:安装、核心概念与工作流

OpenSpec 是一个轻量的规范驱动开发(Spec-Driven Development)框架:在你和 AI 编码助手之间加一层”约定”,先把要做什么写下来,看过计划再写代码,而不是让需求只存在于聊天记录里。它是 MIT 许可的开源项目,支持 30 多个 AI 编码工具,HagiCode 自己的工作流也基于它。本文给出安装和第一次完整流程的最短路径,完整指南在独立站点维护。

核心概念

OpenSpec 由五个概念构成:

规范(specs)是事实来源。 描述系统现在怎么工作,放在 openspec/specs/,按领域组织,由需求和场景组成。
变更(change)是一个工作单元。 要新增、修改或删除行为时,在 openspec/changes/ 下建一个文件夹,把这件事的提案、设计、任务清单和规范修改放在一起。
增量规范(delta specs)只描述变化。 变更里不重写整份规范,而是写 ADDED、MODIFIED、REMOVED,这让它特别适合修改已有系统。
产物按顺序互相衔接。 proposal(为什么)→ specs(做什么)→ design(怎么做)→ tasks(步骤)→ 实现。它们是辅助,不是关卡,随时可以回头改。
归档把变更并回事实。 工作完成后归档,增量规范合并进主规范,变更文件夹移到 changes/archive/ 并加上日期。

安装

前置条件是 Node.js 20.19.0 或更高(HagiCode 的其他组件建议 24 或更高,见安装 Node.js)。

npm install -g @fission-ai/openspec@latest
openspec --version

macOS 和 Linux 也可以用 Homebrew:brew install openspec。pnpm、yarn(1.x)和 bun 同样可以全局安装,但 OpenSpec 仍然运行在 Node.js 上。

然后进入你的项目目录初始化:

cd your-project
openspec init

初始化会询问你用哪些 AI 工具,并为它们生成技能或命令文件。想跳过交互,可以用 openspec init --tools claude,cursor;工具 ID 列表见支持的工具。

第一次完整流程

斜杠命令要输入在 AI 助手的聊天框里,不是终端:

/opsx:explore            # 还没想清楚?先让 AI 读代码、权衡方案
/opsx:propose add-dark-mode   # 生成变更文件夹:proposal、specs、design、tasks
/opsx:apply              # 按任务清单实现
/opsx:archive            # 归档,增量规范并入主规范

/opsx:propose 会生成 openspec/changes/add-dark-mode/,里面有 proposal.md、specs/、design.md 和 tasks.md。规范是普通 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

规范由 AI 来写,你在写代码之前审阅计划。默认配置包含 propose、explore、apply、update、sync、archive;需要 new、continue、ff、verify、bulk-archive 等展开流程时,用 openspec config profile 选择,再运行 openspec update 应用。

命令名在不同助手里略有不同

/opsx:propose 是规范写法。Cursor 和 GitHub Copilot 里是 /opsx-propose,Amazon Q 里是 @opsx-propose,Codex 里是 $openspec-propose。openspec init 会打印你所选工具对应的写法。

升级

npm install -g @fission-ai/openspec@latest   # 升级软件包
openspec update                              # 在每个项目里刷新 AI 指令文件

通过 Homebrew 安装的用 brew upgrade openspec。

常见问题

openspec: command not found:全局 npm 目录不在 PATH 里。运行 npm prefix -g,macOS 和 Linux 把该目录下的 bin/ 加入 PATH,Windows 直接把该目录加入 PATH。
提示需要 Node.js 20.19.0 或更高:用 node --version 检查并升级。
聊天框里找不到 /opsx:propose:确认命令输在助手里而不是终端,运行 openspec update 重新生成文件,再重启助手;Codex 等只支持技能的工具要用 $openspec-propose 这类写法。
初始化没有配置你的工具:重新运行 openspec init,或用 --tools 指定。