OpenSpec安装和基础使用教程

一、准备工作

环境要求

Node.js ≥ 20.19.0（OpenSpec 依赖 Node.js）
已安装 Claude Code（命令行版）

bash 复制代码

# 检查 Node.js 版本
node --version
# 安装 Claude Code（如未装）
curl -fsSL https://claude.ai/install.sh | bash
# 或 npm 全局安装
npm install -g @anthropic-ai/claude-code

安装 OpenSpec CLI

bash 复制代码

# npm 全局安装（推荐）
npm install -g @fission-ai/openspec@latest
# 验证安装
openspec --version
# 查看帮助
openspec --help

二、项目初始化（关键步骤）

进入项目根目录
bash 复制代码
```
cd your-project
```
执行初始化
csharp 复制代码
```
openspec init
```
交互选择：
- AI 助手：选择 Claude Code
- 提案目录：默认 docs/proposals
- 归档目录：默认 docs/archive

初始化后目录结构

bash 复制代码

your-project/
├── .claude/              # Claude Code 配置
│   ├── commands/
│   │   └── openspec/     # 斜杠命令定义
│   │       ├── proposal.md
│   │       ├── apply.md
│   │       └── archive.md
│   └── config.json       # 技能配置
├── openspec/             # OpenSpec 核心目录
│   ├── changes/          # 变更提案
│   ├── specs/            # 规范文档
│   ├── project.md        # 项目上下文
│   └── AGENTS.md         # 工作流说明
└── openspec.config.json  # 配置文件

三、Claude Code 配置（自动完成，可手动校验）

.claude/config.json 会自动添加 OpenSpec 技能：

json 复制代码

{
  "skills": [
    {
      "name": "openspec",
      "trigger": "openspec",
      "description": "OpenSpec 规范驱动开发"
    }
  ]
}

四、在 Claude Code 中使用 OpenSpec

启动 Claude Code
bash 复制代码
```
# 进入项目目录后启动
claude
```

核心斜杠命令（直接在 Claude Code 中输入）

创建变更提案

bash 复制代码

/openspec:proposal "给 Todo 应用添加优先级功能"

自动生成：openspec/changes/add-task-priority/ 目录、提案文档、设计模板、任务清单

应用已批准的变更
bash 复制代码
```
/openspec:apply add-task-priority
```
归档完成的变更
bash 复制代码
```
/openspec:archive add-task-priority
```
查看所有变更
bash 复制代码
```
/openspec:list
```

完整工作流示例
- 填充项目上下文（让 Claude 理解项目）
  arduino 复制代码
```
Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions.
```
- 创建提案
  bash 复制代码
```
/openspec:proposal "实现用户登录功能"
```
- 编辑提案（在 openspec/changes/ 中修改文档）
- 应用变更
  bash 复制代码
```
/openspec:apply user-login
```
- 测试验证后归档
  bash 复制代码
```
/openspec:archive user-login
```

五、常见问题与排查

斜杠命令不生效 ：重启 Claude Code，执行 openspec update 刷新配置
Node.js 版本过低：升级到 ≥ 20.19.0
权限问题 ：用 sudo 执行安装命令（Linux/macOS）

六、CLI 命令速查

csharp 复制代码

openspec init          # 初始化项目
openspec list          # 查看变更列表
openspec show <name>   # 查看变更详情
openspec apply <name>  # 应用变更
openspec archive <name> # 归档变更
openspec validate <name> # 校验规范格式