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
# 输出版本号即成功

三、项目初始化（关键）

1. 进入项目目录

   cd your-project

2. 交互式初始化

   openspec init

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

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

1. 初始化后项目结构

   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，无需重构

八、完整工作流总结

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