OpenSpec + Claude Code 规范驱动开发

在 Windows 上安装和配置 OpenSpec 配合 Claude Code 的完整指南。

前置条件

在开始安装之前，请确保满足以下要求：

💡 如果尚未安装 Node.js，请访问 nodejs.org 下载 LTS 版本安装。

第一步：安装 Claude Code

Claude Code 是 Anthropic 官方推出的命令行智能编程助手，是实际执行编码工作的工具。

1.1 通过 npm 全局安装

以管理员身份打开 PowerShell 或命令提示符（Win + R 输入 cmd，然后右键选择“以管理员身份运行”），执行：

bash

npm install -g @anthropic-ai/claude-code

如果遇到网络问题（国内环境），可以使用国内镜像源：

bash

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

1.2 验证安装

安装完成后执行以下命令验证是否成功：

bash

claude

如果能进入 Claude 的交互界面，说明安装成功。

1.3 配置 AI 模型

Claude Code 本身不内置免费大模型，需要配置 AI 服务商的 API Key。以 DeepSeek 为例，需要在 Windows 系统环境变量中添加以下配置：

Windows 添加环境变量的方法：

1. 右键“此电脑” → 属性 → 高级系统设置 → 环境变量

2. 在“系统变量”区域点击“新建”，依次添加上表中的变量

3. 完成后重启终端

配置完成后，重新打开终端执行 claude，若能正常加载模型，则 Claude Code 配置完毕。可以用 /model 命令检查和选择当前使用的模型。

第二步：安装 OpenSpec

OpenSpec 是规范驱动开发框架，负责生成提案、管理规范和追踪变更。

2.1 通过 npm 全局安装

在终端中执行：

bash

npm install -g @fission-ai/openspec@latest

2.2 验证安装

bash

openspec init --help

如果显示帮助信息，说明安装成功。

第三步：在项目中初始化 OpenSpec

3.1 进入你的项目根目录

bash

cd 你的项目路径

3.2 执行初始化命令

bash

openspec init

3.3 选择 AI 工具环境

初始化过程中，CLI 会询问你要使用哪个 AI 编码助手。在列表中选择 Claude Code。

初始化完成后，OpenSpec 会自动在项目目录下创建以下结构：

text

your-project/
├── openspec/
│   ├── specs/           # 当前已实现的功能规范（“真相”）
│   ├── changes/         # 进行中的变更提案
│   └── archive/         # 已完成的变更归档
└── .claude/
    └── commands/        # Claude Code 的斜杠命令

3.4 在 Claude Code 中激活 OpenSpec

初始化完成后，终端会提示你一段需要复制给 Claude Code 的信息。在 Claude Code 交互界面中粘贴并执行，完成初始化对接。

第四步：验证配置

完成上述步骤后，可以通过以下方式验证 OpenSpec 是否可用：

4.1 在 Claude Code 中测试斜杠命令

启动 Claude Code：

bash

claude

在 Claude Code 交互界面中输入：

text

/opsx:new

如果 OpenSpec 已正确集成，Claude Code 会响应并启动创建变更提案的流程。

4.2 查看可用的 OpenSpec 命令

在 Claude Code 中输入 / 查看命令列表，应该能看到以下 OPSX 工作流命令：

故障排查

问题 1：npm install 报错或速度慢

• 使用国内镜像源：--registry=https://registry.npmmirror.com

• 或使用代理：npm config set proxy http://你的代理地址

问题 2：openspec init 无法识别命令

• 检查 Node.js 版本：node -v，确保 ≥ 20.19.0

• 检查 OpenSpec 是否安装成功：openspec --version

• 尝试重新安装：npm install -g @fission-ai/openspec@latest

问题 3：Claude Code 无法连接到 API

• 检查环境变量是否正确配置（尤其是 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL）

• 配置后必须重启终端才能生效

• 在 Claude Code 中用 /model 命令确认当前使用的模型

问题 4：斜杠命令 /opsx:xxx 不可用

• 确保在项目根目录下运行 Claude Code（该目录包含 openspec/ 文件夹）

• 重新运行 openspec init，确保选择了 Claude Code 作为目标环境

可选：更轻量的替代方案

如果你希望获得 OpenSpec 的工作流体验，但又不想安装和记忆 CLI 命令，可以了解 Skilled Spec。它是 OpenSpec 方法论的 Claude Code 原生技能集，通过自然语言即可驱动整个工作流，无需任何 CLI 安装。

安装方式（在项目根目录执行）：

bash

npx skilled-spec-cn@latest

之后直接在 Claude Code 中用中文描述需求即可，例如“我想创建一个用户认证的提案”。

以上就是在 Windows 上安装配置 OpenSpec 配合 Claude Code 的完整步骤。如果遇到其他问题，欢迎进一步交流！