一、为什么我们需要新的 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 <id> # 校验规范完整性
openspec show <id> # 查看变更详情
这一步的工程意义是：
在写代码前，把“错误需求”拦下来
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 <change>
OpenSpec 会：
- 把变更移入 archive/
- 将核心规范合并进 specs/
- 标记该需求为“历史决策”
这一步解决的是一个长期痛点：
为什么这个功能当初要这么设计？
