一、准备工作
-
环境要求
- Node.js ≥ 20.19.0（OpenSpec 依赖 Node.js）
- 已安装 Claude Code（命令行版）
# 检查 Node.js 版本 node --version # 安装 Claude Code（如未装） curl -fsSL https://claude.ai/install.sh | bash # 或 npm 全局安装 npm install -g @anthropic-ai/claude-code -
安装 OpenSpec CLI
# npm 全局安装（推荐） npm install -g @fission-ai/openspec@latest # 验证安装 openspec --version # 查看帮助 openspec --help
二、项目初始化（关键步骤）
-
进入项目根目录
cd your-project -
执行初始化
openspec init -
交互选择：
- AI 助手：选择 Claude Code
- 提案目录：默认
docs/proposals - 归档目录：默认
docs/archive
-
初始化后目录结构
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 技能：
{
"skills": [
{
"name": "openspec",
"trigger": "openspec",
"description": "OpenSpec 规范驱动开发"
}
]
}
四、在 Claude Code 中使用 OpenSpec
-
启动 Claude Code
# 进入项目目录后启动 claude -
核心斜杠命令（直接在 Claude Code 中输入）
-
创建变更提案
/openspec:proposal "给 Todo 应用添加优先级功能" 自动生成：openspec/changes/add-task-priority/ 目录、提案文档、设计模板、任务清单 -
应用已批准的变更
/openspec:apply add-task-priority -
归档完成的变更
/openspec:archive add-task-priority -
查看所有变更
/openspec:list
-
-
完整工作流示例
-
填充项目上下文（让 Claude 理解项目）
Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions. -
创建提案
/openspec:proposal "实现用户登录功能" -
编辑提案（在
openspec/changes/中修改文档） -
应用变更
/openspec:apply user-login -
测试验证后归档
/openspec:archive user-login
-
五、常见问题与排查
- 斜杠命令不生效：重启 Claude Code，执行
openspec update刷新配置 - Node.js 版本过低：升级到 ≥ 20.19.0
- 权限问题：用
sudo执行安装命令（Linux/macOS）
六、CLI 命令速查
openspec init # 初始化项目
openspec list # 查看变更列表
openspec show <name> # 查看变更详情
openspec apply <name> # 应用变更
openspec archive <name> # 归档变更
openspec validate <name> # 校验规范格式
