基于 OpenSpec + Claude CLI 的实战开发指南

一、为什么我们需要新的 AI 开发方式？

很多开发者已经在用 ChatGPT、Claude 写代码了，但普遍有三个痛点：

上下文不稳定

每次提问都要重新解释项目结构、技术栈、规范。

生成结果不可控

AI 有时写得很好，有时完全跑偏，风格、架构不统一。

无法工程化

只能"对话式写代码"，难以融入 CI / 本地开发流程。

这正是 OpenSpec + Claude CLI 组合要解决的问题：

把 AI 从"聊天工具"升级为"受规范约束的开发工具"

二、工具介绍：OpenSpec 和 Claude CLI 是什么？

1.OpenSpec：给 AI 的「工程说明书」

OpenSpec 本质上是一套 结构化的工程规范描述方式，用于告诉 AI：

• 项目是做什么的
• 使用什么技术栈
• 代码风格、架构约束
• 安全、性能、边界规则
• 你"允许 AI 做什么，不允许做什么"

你可以把它理解为：

AI 版本的《项目技术设计文档 + 编码规范》

示例（简化）：

project:

  name: user-service

  language: Java

  framework: Spring Boot 3.x

rules:

  - 禁止直接操作数据库，必须通过 Repository

  - Controller 只做参数校验和转发

  - 所有接口必须返回统一 Result<T>

2.Claude CLI：真正进入你本地工程的 AI

Claude CLI 是 Anthropic 官方提供的命令行工具，它的优势是：

• 可直接访问本地代码
• 可结合 OpenSpec 使用
• 适合"多文件、重构、理解项目"的任务
• 比 Web 聊天更稳定、可复现

三、OpenSpec + Claude CLI 的协作模式

整体流程如下：

OpenSpec（规范 & 约束）-> Claude CLI（理解规范）

在真实项目中执行开发任务

一句话总结：

OpenSpec 决定"边界"，Claude CLI 负责"执行"

四、实战：一步步搭建 OpenSpec + Claude CLI 开发环境

Step 1：安装 Claude CLI

前提：已配置 Claude API Key

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

验证安装：

claude --version

Step 2：在项目中创建 OpenSpec

先决条件

• Node.js ≥ 20.19.0
• 本地已有代码仓库（Git 项目）

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

验证是否成功：

openspec --version

Step 3：让 Claude CLI 读取 OpenSpec

在项目根目录执行：

进入你的项目目录：

cd your-project-directory

openspec init

初始化过程中，OpenSpec 会做几件非常关键的事：

✅ 1. 绑定 AI 工具

你会被提示选择当前使用的 AI，例如：

• Claude Code / Claude CLI
• Cursor
• GitHub Copilot（偏弱）

这一步的意义 ：

OpenSpec 不是单独运行，而是挂载在 AI 编程工具之上。

✅ 2. 注入斜杠命令（Slash Commands）

比如：

• /openspec:proposal
• /openspec:apply
• /openspec:archive

这些命令不是 shell 命令，而是：

"给 AI 的工程级操作指令"

✅ 3. 创建 OpenSpec 工作目录

初始化后，你会看到：

openspec/

├── specs/ # 规范（长期有效）

├── changes/ # 变更提案（一次性）

└── archive/ # 已完成变更

这一点非常重要：

OpenSpec 把「需求规范」和「实现变更」彻底分离了

五、实战场景一：新增一个业务接口

Step 1：起草变更提案（Proposal）

当你有一个新需求时，不是直接让 AI 写代码，而是：

/openspec:proposal Add user list API

这一步做的是：

�� 把"模糊需求"变成"结构化变更"

AI 会自动生成一个变更目录，例如：

openspec/changes/add-user-list-api/

├── proposal.md

├── tasks.md

└── spec.md

每个文件的职责是：

• proposal.md为什么要做这个变更？解决什么问题？
• tasks.md拆解为哪些实现步骤？是否可以并行？
• spec.md精确描述接口、参数、边界、场景

关键点：
此时还没有写一行代码

Step 2：验证与审查（像 Review 需求一样）

OpenSpec 把"需求 Review"变成了一个可执行动作。

openspec list # 查看所有活跃变更

openspec validate # 校验规范完整性

openspec show # 查看变更详情

这一步的工程意义是：

在写代码前，把"错误需求"拦下来

Step 3：与 AI 迭代完善规范（不是改代码）

例如你对 AI 说：

"给用户列表 API 增加分页和排序场景"

AI 会：

• 只更新 spec.md
• 不会碰实现代码
• 不会偷偷"顺手写功能"

这一步本质是：

把 AI 当成「需求分析师 + 架构助理」

Step 4：实施变更（ Apply）

当你确认规范已经 OK：

/openspec:apply <change>

这一步才是 AI 开始写代码。

但注意：

• AI 严格按照 tasks.md
• 每个任务都有完成状态
• 不允许"自由发挥"

Step 5：归档变更（Archive）

当功能完成、测试通过：

/openspec:archive

OpenSpec 会：

• 把变更移入 archive/
• 将核心规范合并进 specs/
• 标记该需求为"历史决策"

这一步解决的是一个长期痛点：

为什么这个功能当初要这么设计？