OpenSpec安装和基础使用教程

一、准备工作

1. 环境要求
   • Node.js ≥ 20.19.0（OpenSpec 依赖 Node.js）
   • 已安装 Claude Code（命令行版）

   bash 体验AI代码助手 代码解读复制代码# 检查 Node.js 版本 node --version # 安装 Claude Code（如未装） curl -fsSL https://claude.ai/install.sh | bash # 或 npm 全局安装 npm install -g @anthropic-ai/claude-code

2. 安装 OpenSpec CLI bash 体验AI代码助手 代码解读复制代码# npm 全局安装（推荐） npm install -g @fission-ai/openspec@latest # 验证安装 openspec --version # 查看帮助 openspec --help

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

1. 进入项目根目录 bash 体验AI代码助手 代码解读复制代码cd your-project
2. 执行初始化 csharp 体验AI代码助手 代码解读复制代码openspec init
3. 交互选择：
   • AI 助手：选择 Claude Code
   • 提案目录：默认 docs/proposals
   • 归档目录：默认 docs/archive
4. 初始化后目录结构 bash 体验AI代码助手 代码解读复制代码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 技能： https://drive.google.com/file/d/1YOEwDgag3OjSxBMX9AonDQBj4i_d_60E/view?usp=sharing

json 体验AI代码助手 代码解读复制代码{
  "skills": [
    {
      "name": "openspec",
      "trigger": "openspec",
      "description": "OpenSpec 规范驱动开发"
    }
  ]
}

四、在 Claude Code 中使用 OpenSpec

1. 启动 Claude Code bash 体验AI代码助手 代码解读复制代码# 进入项目目录后启动 claude
2. 核心斜杠命令（直接在 Claude Code 中输入）
   • 创建变更提案 bash 体验AI代码助手 代码解读复制代码/openspec:proposal "给 Todo 应用添加优先级功能" ​ 自动生成：openspec/changes/add-task-priority/ 目录、提案文档、设计模板、任务清单
   • 应用已批准的变更 bash 体验AI代码助手 代码解读复制代码/openspec:apply add-task-priority
   • 归档完成的变更 bash 体验AI代码助手 代码解读复制代码/openspec:archive add-task-priority
   • 查看所有变更 bash 体验AI代码助手 代码解读复制代码/openspec:list
3. 完整工作流示例
   • 填充项目上下文（让 Claude 理解项目） arduino 体验AI代码助手 代码解读复制代码Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions.
   • 创建提案 bash 体验AI代码助手 代码解读复制代码/openspec:proposal "实现用户登录功能"
   • 编辑提案（在 openspec/changes/ 中修改文档）
   • 应用变更 bash 体验AI代码助手 代码解读复制代码/openspec:apply user-login
   • 测试验证后归档 bash 体验AI代码助手 代码解读复制代码/openspec:archive user-login

五、常见问题与排查

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

六、CLI 命令速查

csharp 体验AI代码助手 代码解读复制代码openspec init          # 初始化项目
openspec list          # 查看变更列表
openspec show <name>   # 查看变更详情
openspec apply <name>  # 应用变更
openspec archive <name> # 归档变更
openspec validate <name> # 校验规范格式