02 - 让 AI 照着契约写代码？OpenSpec 从零上手：npm 命令安装OpenSpec让 AI 照着契约写代码

让 AI 照着契约写代码？OpenSpec 从零上手：一条 npm 命令装出整套「规范引擎」

一句话：OpenSpec 是一套「规范驱动的变更管理」工具箱，由一个 CLI（openspec 命令）+ 一套 AI Skill（/opsx:xxx 指令）组成。本文是纯安装向的保姆级教程——从检查 Node 版本开始，到 npm 全局安装，再到进入项目执行 openspec init、交互式选择你的开发工具（Claude Code / Cursor / Codex…），选择后它自动生成该工具专属的 Skill 与命令，以及 openspec/ 规范目录。一步步带你装好、验证、用起来。

核心就记住一件事：OpenSpec = 终端命令（openspec ...）+ AI 指令（/opsx:...），两者要配合使用，缺一不可。

一、前置检查：Node 版本别踩坑

OpenSpec 包对运行时有硬性要求：Node.js >= 20.19.0。版本低了，装完命令会直接报错。

先敲两行命令自查：

node --version   # 本机示例输出：v22.17.1
npm --version

检查项	要求	示例
Node.js	`>= 20.19.0`	✅ v22.17.1
npm	随 Node 自带	✅ 无特殊要求

⚠️ 建议先确认版本再安装，别等装完发现跑不起来再回头升级 Node。

二、安装：一条命令，注意包名

主推 npm 全局安装：

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

三个关键点，任何一个错了都白搭：

包名是 @fission-ai/openspec，不是 openspec——npm install -g openspec 装的是另一个无关的包，这是最常见的坑。
-g 全局安装，装完会生成一个 openspec 可执行命令。
@latest 拉最新稳定版（写作本文时最新为 1.7.0）。

其他包管理器官方都支持，任选其一：

pnpm add -g @fission-ai/openspec@latest   # pnpm
yarn global add @fission-ai/openspec@latest  # yarn
bun add -g @fission-ai/openspec@latest    # bun（仍需 Node >=20.19.0 在 PATH 中）
nix run github:Fission-AI/OpenSpec -- init  # nix，无需安装直接跑

装完去哪了？（理解一下）

which openspec
# /usr/local/bin/openspec

ls -la /usr/local/bin/openspec
# lrwxr-xr-x ... -> ../lib/node_modules/@fission-ai/openspec/bin/openspec.js

npm ls -g --depth=0 | grep openspec
# ├── @fission-ai/openspec@1.7.0

可以理解为：npm 把包装进全局 node_modules，再在 /usr/local/bin/ 建了一个指向 bin/openspec.js 的软链。搞懂这一点，后面排查「命令找不到」会容易很多。

三、验证安装：三步走

openspec --version
# 1.7.0

openspec --help
# 输出命令列表：init / update / list / change / archive / validate / sync 等

能看到版本号和命令列表，安装即成功。

四、初始化项目：`openspec init` —— 交互式选择你的开发工具

这是本文的核心。新版 OpenSpec 把「初始化项目」和「生成 AI Skill」合并成了一步：openspec init 会引导你选择日常使用的 AI 开发工具，选完之后自动完成该工具的 Skill 安装，不需要再单独跑命令。

4.1 执行 init，进入工具选择

在项目根目录执行：

cd your-project
openspec init

终端会进入交互式选择界面，列出 OpenSpec 支持的全部 AI 编程工具（写作本文时共 33 种），用方向键 / 序号选中你平时写代码用的那个：

Amazon Q / Antigravity / Auggie / Bob / Claude Code / Cline / CodeArts / Codex / Devin(原 Windsurf) / Cursor / Factory / Gemini CLI / GitHub Copilot / Hermes / Junie / Kilo Code / Kimi Code / Kiro / Lingma / Qwen / Trae / Zoo Code / ……

选好后回车，终端自动 setup。以选择 Claude Code 为例，实测输出长这样：

- Creating OpenSpec structure...
▌ OpenSpec structure created
- Setting up Claude Code...
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

4.2 选择 Claude Code 后，自动生成了什么

init 完成后，项目根目录自动多出两部分：

your-project/
├── .claude/                  ← 工具专属（选哪个工具，就生成到哪个工具的目录）
│   ├── skills/                ← 6 个 Skill
│   │   ├── openspec-explore/        想清楚（thinking partner）
│   │   ├── openspec-propose/        提方案（proposal + spec + design + tasks）
│   │   ├── openspec-apply-change/   按单实现
│   │   ├── openspec-sync-specs/     合并规格
│   │   ├── openspec-archive-change/ 归档变更
│   │   └── openspec-update-change/  修订变更
│   └── commands/opsx/        ← 6 个命令（AI 对话里的快捷入口）
│       ├── explore.md / propose.md / apply.md / sync.md / archive.md / update.md
└── openspec/                 ← 规范目录（与工具无关，所有工具共享）
    ├── config.yaml            ← 项目上下文（技术栈 / 规则约束）
    ├── changes/               ← 变更目录（含 archive/，初始为空）
    └── specs/                 ← 主规格（初始为空，待 sync 合并）

4.3 真实项目落地长这样

项目里实测为例（init 时选了 Claude Code），磁盘上自动落盘为：

├── .claude/
│   ├── skills/
│   │   ├── openspec-explore/SKILL.md
│   │   ├── openspec-propose/SKILL.md
│   │   ├── openspec-apply-change/SKILL.md
│   │   ├── openspec-sync-specs/SKILL.md
│   │   ├── openspec-archive-change/SKILL.md
│   │   └── openspec-update-change/SKILL.md
│   └── commands/opsx/{explore,propose,apply,sync,archive,update}.md
└── openspec/
    ├── config.yaml
    ├── changes/
    └── specs/

openspec/ 是项目规范仓库，由所有工具共享；.claude/ 里的 skills / commands 是「把这套规范接进 Claude Code」的桥。

4.4 工具差异：Skill 落在哪、怎么调用都不一样

选不同的工具，生成目录和 AI 对话里的调用方式完全不同。下表为关键工具实测：

开发工具	生成目录	产物	AI 对话里的调用方式
Claude Code	`.claude/skills` + `.claude/commands/opsx`	6 skills + 6 commands	`/opsx:propose "想法"`
Cursor	`.cursor/skills` + `.cursor/commands`	6 skills + 6 commands	`/opsx-propose "想法"`
Codex	`.codex/skills`	6 skills（无 commands）	`$openspec-propose "想法"`
Amazon Q	`.amazonq/...`	skills + commands	`@opsx-propose "想法"`
Kimi Code	`.kimi-code/skills`	6 skills	`/skill:openspec-propose "想法"`
Devin(原 Windsurf)	`.devin/...`	skills + commands	`/openspec-propose "想法"`
…	各工具专属隐藏目录	6 skills ± commands	各不相同

共同点：无论选哪个工具，openspec/ 规范目录都会生成且完全一致——它是所有工具共享的「契约仓库」；差异只在你选的工具各自的 skill 目录和调用方式。

4.5 非交互式指定：`--tools` 参数

不想一个个敲回车，或用脚本批量初始化，可以用 --tools 直接指定：

openspec init --tools claude              # 只装 Claude Code
openspec init --tools cursor,codex        # 同时装多个，逗号分隔
openspec init --tools all                 # 33 种全装
openspec init --tools none                # 只建 openspec/ 规范目录，不装任何 skill

在已有项目上再次 openspec init --tools xxx 也是安全的：它会追加生成新工具的目录，不会动已装的其他工具和已有 openspec/。实测在已有 .claude/ 的项目里补 --tools cursor，会新增 .cursor/ 而 .claude/ 原样保留，config.yaml 复用。

4.6 config.yaml：把项目上下文喂给 AI

config.yaml 是「项目规范 ↔ OpenSpec」的桥，它会把技术栈和约束注入到每个工件生成过程，AI 照着这些规则产出，才不会自由发挥。下面是一个示意格式（请按你自己的项目实际情况填写，不要照抄）：

schema: spec-driven
context: |
  移动端 H5 应用。
  技术栈：React 18 + MobX + antd-mobile-v2。
  设计规范：750px 设计稿，px 自动转 vw。
rules:
  proposal:
    - 提案需明确背景、目标、范围（包含/不包含）、影响、风险与验收标准
  specs:
    - 规格使用 delta 格式（## ADDED / ## MODIFIED），每条需求包含场景块
  design:
    - 设计需描述页面结构、数据流、状态与接口契约、组件边界
  tasks:
    - 任务按阶段递进、可执行可验证，每阶段完成后再进入下一阶段

留意：config.yaml 的格式务必以 CLI 源码/schema 为准，官方文档示例可能过时。有项目曾因示例格式与实际版本不符，导致配置被静默忽略——排查时可先用 openspec validate 验证。

五、换工具 / 加工具 / 升级后同步：`openspec update`

init 已把工具 setup 一步做完，所以「生成 AI Skill」不再是独立步骤。openspec update 现在的职责是事后同步：

CLI 升级后，刷新项目里已配置工具的 skill 文件；
它会自动检测项目已装哪些工具，只在有差异时更新，已最新则提示 up to date。

openspec update            # 刷新已配置工具的 skill
openspec update --force    # 强制覆盖刷新

实测输出（项目里已装过 Claude Code 时）：

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude
Use --force to refresh files anyway.

小提示：给已有项目加新工具，直接 openspec init --tools 新工具 即可，比手动折腾 skill 目录省事得多。

六、完整流程速查：从零到用起来

# 1. 检查前置
node --version                     # 需 >= 20.19.0

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

# 3. 验证
openspec --version                 # 如 1.7.0

# 4. 进入项目初始化，交互式选择开发工具
cd your-project && openspec init   # 选 Claude Code / Cursor / Codex …
#   → 自动生成 .claude/skills/openspec-* 与 openspec/{specs,changes,config.yaml}

# 5. 开始使用
openspec list                      # 查看现有变更
# 在 AI 对话里直接：/opsx:propose "想法"

跑完这五步，你就拥有了「终端管理变更 + AI 按规范实现」的完整闭环。

七、升级与卸载

升级（两步走）

npm install -g @fission-ai/openspec@latest   # 升级 CLI
openspec update                              # 同步刷新项目内 skill 文件

官方建议：升级包之后，每个项目的生成文件也要跑一次 openspec update 保持同步。换环境、重装后尤其容易漏。

卸载

npm uninstall -g @fission-ai/openspec

没有 openspec uninstall 命令——它只是「全局 npm 包 + 项目文件」的组合，删掉全局包即可；项目里的 openspec/ 目录和 .claude/skills/openspec-* 需要手动删除。

八、新手最常见的 4 个坑

Node 版本过低：openspec 要求 >=20.19.0，低于此版本安装后命令可能直接报错。
装成别的包：手滑装成 npm install -g openspec，那是另一个无关包；必须是 @fission-ai/openspec。
工具选错 / 选多：init 时选错工具，AI 对话里就会出现你那个工具没有的调用方式。不用慌——在已有项目上重跑 openspec init --tools 正确工具 即可补齐；同时也不要无脑装 all，装 33 种工具的 skill 只会让项目更乱，按需用 --tools 精准指定。
换环境 / CLI 升级后 skill 不更新：旧项目的 .claude/skills/openspec-* 需重新执行 openspec update 刷新。

九、总结

OpenSpec 的安装本质上就三件事：

npm install -g @fission-ai/openspec@latest —— 装上 CLI（注意包名）。
openspec init —— 交互式选择开发工具，自动生成该工具的 6 个 Skill / 命令 + openspec/（specs/ + changes/ + config.yaml）。
openspec update —— 事后同步：换环境、CLI 升级后刷新 skill。

装完之后，「终端管理变更」和「AI 按规范实现」这两半就拼起来了：

先想清楚（explore）→ 再写契约（propose）→ 按单实现（apply）→ 合并规格（sync）→ 关闭变更（archive）。

02 - 让 AI 照着契约写代码？OpenSpec 从零上手：npm 命令安装OpenSpec