OpenSpec 安装与使用指南

什么是 OpenSpec

OpenSpec 是一个规范驱动开发（Spec-Driven Development）工具，集成在 Claude Code 中。它将开发过程分为四个阶段：探索 → 提案 → 实现 → 归档，通过规范化的 artifacts（提案、设计、规格、任务）来驱动开发流程。

安装

前提条件

• Node.js >= 20.19.0
• Claude Code（已安装）

步骤

# 1. 全局安装 OpenSpec CLI
npm install -g @fission-ai/openspec@latest

# 2. 验证安装
openspec --version

# 3. 在项目根目录初始化（交互式）
cd your-project
openspec init

# 或者跳过交互，直接指定工具
openspec init --tools claude

初始化后生成的文件

your-project/
├── .claude/
│   ├── commands/opsx/          # 4 个斜杠命令
│   │   ├── explore.md          # /opsx:explore
│   │   ├── propose.md          # /opsx:propose
│   │   ├── apply.md            # /opsx:apply
│   │   └── archive.md          # /opsx:archive
│   └── skills/                 # 4 个技能定义
│       ├── openspec-explore/SKILL.md
│       ├── openspec-propose/SKILL.md
│       ├── openspec-apply-change/SKILL.md
│       └── openspec-archive-change/SKILL.md
├── openspec/
│   ├── specs/                  # 当前规范（"真相来源"）
│   ├── changes/                # 活跃的变更提案
│   └── archive/                # 已完成的变更
└── .openspec.yaml              # OpenSpec 配置

重要： 初始化后需要重启 IDE 让斜杠命令生效。

四阶段工作流

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Explore  │───▶│ Propose  │───▶│  Apply   │───▶│ Archive  │
│  探索    │    │  提案    │    │  实现    │    │  归档    │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
     │                                                     │
     └─────────────── 随时可以回去探索 ◀───────────────────┘

1. Explore（探索模式） — /opsx:explore

用途： 在动工之前理清思路、探索问题空间。

使用方式：

/opsx:explore                    # 进入探索模式
/opsx:explore 添加用户认证        # 探索特定问题
/opsx:explore add-auth           # 在已有变更上下文中探索

特点：

• 只思考，不实现 — 可以读代码、搜索，但不能写代码
• 没有固定流程，是思考伙伴
• 结束时可以自然过渡到创建提案

适合场景：

• 梳理模糊的想法
• 比较技术方案（例如 “用 Redis 还是 SQLite”）
• 理解现有代码的复杂点
• 卡在实现中需要理清思路

---

2. Propose（提案） — /opsx:propose

用途： 一键创建变更的所有 artifacts。

使用方式：

/opsx:propose add-user-auth                # 指定变更名
/opsx:propose                              # 不指定，会询问你想做什么
/opsx:propose "添加新的下载器中间件"         # 描述你的想法

生成的文件：

Artifact	文件	内容
Proposal	proposal.md	做什么 & 为什么（what & why）
Design	design.md	怎么做（how）
Tasks	tasks.md	实现步骤（implementation steps）

流程：

1. Claude Code 用 openspec new change "<name>" 创建变更目录
2. 通过 openspec status --change "<name>" --json 获取 artifact 列表和依赖关系
3. 对每个 artifact，通过 openspec instructions <id> --change "<name>" --json 获取模板和约束
4. 按依赖顺序逐一创建 artifacts
5. 全部完成后显示总结

---

3. Apply（实现） — /opsx:apply

用途： 按 tasks.md 中的任务列表逐步实现变更。

使用方式：

/opsx:apply                     # 自动选择或询问变更
/opsx:apply add-user-auth       # 指定变更名

流程：

1. 选择变更（如果有多个会询问）
2. 检查状态（openspec status --change "<name>" --json）
3. 获取实现指令（openspec instructions apply --change "<name>" --json）
4. 读取所有 context 文件（proposal + design + tasks）
5. 逐任务实现，完成一个勾一个（[ ] → [x]）
6. 全部完成后提示可以归档

暂停条件：

• 任务不清晰 → 询问
• 实现发现设计问题 → 建议更新 artifacts
• 遇到错误/阻塞 → 报告并等待

---

4. Archive（归档） — /opsx:archive

用途： 完成后归档变更，将 delta specs 同步到主 specs。

使用方式：

/opsx:archive                   # 选择要归档的变更
/opsx:archive add-user-auth     # 指定变更名

流程：

1. 选择变更
2. 检查 artifacts 和 tasks 是否全部完成
3. 如果有 delta specs，提示是否同步到主 specs
4. 移动到 openspec/archive/YYYY-MM-DD-<name>/

---

CLI 命令参考

命令	说明
openspec init	初始化 OpenSpec 到当前项目
openspec init --tools claude	指定只配置 Claude Code
openspec new change "<name>"	创建新变更
openspec list --json	列出所有变更
openspec status --change "<name>" --json	查看变更状态
openspec instructions <artifact> --change "<name>" --json	获取 artifact 模板和指令
openspec instructions apply --change "<name>" --json	获取实现指令
openspec update	更新配置（新增工具支持时用）

项目结构说明

在生成的 .claude/ 目录中有两个核心部分：

Commands（命令）

位于 .claude/commands/opsx/，是用户触发的入口。每个 .md 文件定义了用户输入 /opsx:xxx 后 Claude 的行为。

Skills（技能）

位于 .claude/skills/，是命令的内部实现。每个 SKILL.md 是一个完整的 skill 定义，包含 frontmatter 元数据和详细的执行指令。

两者的关系：

• Commands 定义了用户可见的斜杠命令（触发方式）
• Skills 定义了Claude 执行的具体逻辑（内部实现）
• 一个 Command 通常对应一个 Skill

SKILL.md 结构

---
name: openspec-propose           # 技能名称
description: ...                 # 简短描述
license: MIT
compatibility: Requires openspec CLI.
metadata:
  author: openspec
  version: "1.0"
  generatedBy: "1.4.1"
---

# 这里是具体的执行指令
# 包含：Input、Steps、Output、Guardrails

SKILL.md 中的内容就是 Claude Code 在调用该 skill 时遵循的工作指令。这是一个 Claude.md 文件的高优先级（star 很高）版本 — 它定义了 Claude 如何处理特定类型的工作。

常见问题

斜杠命令不出现

重启 IDE/Claude Code，或运行 openspec update 刷新配置。

如何新增一个工具

openspec update --tools claude,cursor

想从其他工具迁移

OpenSpec 支持多种 AI 工具（Claude Code、Cursor、Codex 等），在 openspec init 时可多选。