OpenSpec安装、使用步骤

https://mp.weixin.qq.com/s/odSXvpnsIGVT6-uNHGL86Q

OpenSpec 是一个面向 AI 编程助手（如 Claude Code、Cursor）的规范驱动开发（SDD）框架，通过结构化工作流让 AI 代码生成更可控、可追溯、更符合规范。

一、环境准备（必备）

Node.js 20.19.0 或更高版本

- 下载：https://nodejs.org/
- 验证：node -v、npm -v

二、全局安装 OpenSpec

打开终端（Windows 用 Git Bash/WSL），执行：

复制代码

# npm（推荐）
npm install -g @fission-ai/openspec@latest

# 或 pnpm
pnpm add -g @fission-ai/openspec@latest

# 或 yarn
yarn global add @fission-ai/openspec@latest

# 或 bun
bun add -g @fission-ai/openspec@latest

验证安装

复制代码

openspec --version
# 输出版本号即成功

三、项目初始化（关键）

进入项目目录

cd your-project
交互式初始化

openspec init

- 选择你使用的 AI 工具：Claude Code、Cursor、Copilot 等
- 确认目录（默认即可）：

- - 提案目录：docs/proposals
  - 归档目录：docs/archive

初始化后项目结构

your-project/
├── openspec/ # 核心目录
│ ├── specs/ # 系统规范（源真相）
│ ├── changes/ # 变更提案（每个需求一个目录）
│ ├── project.md # 项目上下文（技术栈、规范）
│ └── AGENTS.md # AI 工作流说明
├── openspec.config.json# 配置文件
└── .claude/ (或 .cursor/) # AI 助手配置

四、基础使用流程（OPSX 命令）

在 Claude Code/Cursor 对话中直接输入以下斜杠命令：

1. 新建变更提案

复制代码

# 格式：/opsx:new <需求描述>
/opsx:new 给Todo应用添加深色模式

自动生成：openspec/changes/add-dark-mode/
包含文件：proposal.md、design.md、tasks.md、specs/

2. 快速生成完整方案

复制代码

/opsx:ff  # fast-forward：自动完善提案、设计、任务、规范

3. 让 AI 按规范实现代码

复制代码

/opsx:apply

AI 严格按 tasks.md 和 specs/ 编写代码
自动保持与项目规范一致

4. 完成后归档（沉淀规范）

复制代码

/opsx:archive

将变更合并到主 specs/
历史可追溯、新需求可复用

五、常用 CLI 命令（终端）

复制代码

# 查看所有进行中的变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 验证规范格式
openspec validate add-dark-mode

# 更新 AI 命令文件（升级 OpenSpec 后执行）
openspec update

# 交互式仪表板
openspec view

六、推荐配置（项目上下文）

编辑 openspec/project.md，告诉 AI 项目细节：

复制代码

# 项目上下文
技术栈：TypeScript + React 18 + Node.js + PostgreSQL
API 风格：RESTful
测试框架：Vitest
代码规范：ESLint + Prettier

七、常见问题

命令不生效 ：重新执行 openspec init 或 openspec update
AI 不理解命令：确保用支持的 AI 工具（Claude Code、Cursor）
旧项目集成 ：直接 cd 进项目、openspec init，无需重构

八、完整工作流总结

安装 → npm install -g ...
初始化 → openspec init
提需求 → /opsx:new 需求
定方案 → /opsx:ff
写代码 → /opsx:apply
归档 → /opsx:archive