AI Coding：用 OpenSpec 让 Claude Code 先对齐再动手
在 AI 编程时代，”vibe coding” 很爽，但 AI 改着改着就跑偏了。OpenSpec 是一个轻量级的 Spec-Driven Development（SDD）框架，它不改变你现有的工具链，只是让 Claude Code 在写代码之前，先跟你把”要做什么”对齐清楚。本文介绍 OpenSpec 的核心概念，并手把手教你用普通 Claude Code搭配 OpenSpec 完成一次规范驱动开发。
一、OpenSpec 是什么
OpenSpec 是由 Fission AI 开源的规范驱动开发框架，MIT 协议，通过 npm 安装，生成的所有产物都是纯 Markdown 文件，直接放在你的代码仓库里。
它的核心思想很简单：先写 Spec，再写 Code。
传统 AI 编程的问题在于，需求只存在于聊天记录中，AI 容易：
- 理解偏了，实现出来的东西不对
- 每次新开对话要重新解释项目背景
- 改着改着偏离原始意图
OpenSpec 的做法是在项目里建立一套规范库（Source of Truth），每次变更都先产出 proposal.md（为什么做）、specs/（需求规范）、design.md（技术方案）、tasks.md（任务清单），AI 按清单执行，实现完再归档合并。
它不调用 LLM、不收费、不锁死工具，你现有的 Claude Code、Cursor、Cline 都能用。
二、为什么需要 OpenSpec
表格
| 痛点 | OpenSpec 的解法 |
|---|---|
| AI 每次对话都要重新理解项目 | AGENTS.md + openspec/specs/ 持久化项目上下文，AI 随时读取 |
| AI 改着改着偏离需求 | proposal.md + tasks.md 锁定目标，AI 按清单执行 |
| 需求只在聊天记录里，无法追溯 | 所有规范都是 Markdown 文件，进 Git，可审计 |
| 多人协作时 AI 行为不一致 | 统一规范库，换哪个 AI 工具来都能对齐 |
OpenSpec 的 Delta 跟踪机制（ADDED / MODIFIED / REMOVED）特别适合在已有项目（Brownfield）上迭代，而不是只能从零开始。
三、安装 Claude Code
OpenSpec 本身不调用 LLM，它只是生成规范文件，实际执行代码的还是你的 AI 工具。这里以 Claude Code 为例。
前置要求
- Node.js 20+
- 一个 Anthropic API Key（console.anthropic.com 获取）
安装方式
方式一：官方脚本（推荐）
bash
curl -fsSL https://claude.ai/install.sh | bash方式二：npm 安装
bash
npm install -g @anthropic-ai/claude-code配置 API Key
bash
export ANTHROPIC_API_KEY="sk-ant-xxx..."建议写入 ~/.bashrc 或 ~/.zshrc 永久生效：
bash
echo 'export ANTHROPIC_API_KEY="sk-ant-xxx..."' >> ~/.bashrc
source ~/.bashrc验证安装：
bash
claude --version
四、安装 OpenSpec
OpenSpec 是一个 npm CLI 工具，安装非常简单：
bash
npm install -g @fission-ai/openspec验证：
bash
openspec --version
五、在项目里初始化 OpenSpec
进入你的项目根目录，执行：
bash
openspec init
你会看到一个交互式选择界面，让你选择要集成的 AI 工具。用 ↑↓ 移动光标，Space 选中，Enter 确认：
✔ Select tools to set up (30 available)
○ Cline
● Claude Code ← 选中
○ Codex
○ Continue
...选择 Claude Code 后，OpenSpec 会在项目里生成以下结构：
openspec/
├── specs/ # 项目规范库（Source of Truth）
├── changes/ # 当前活跃的变更提案
│ └── archive/ # 已归档的变更
└── config.yaml # 项目配置
.claude/
└── skills/ # Claude Code 的 skills 和 commands
AGENTS.md # 给 AI 看的项目上下文说明
六、实战：用 OpenSpec + Claude Code 完成一次变更
OpenSpec 的核心工作流是 OPSX，默认提供四条命令：
| 命令 | 作用 |
|---|---|
/opsx:propose | 创建提案，生成规范、设计、任务清单 |
/opsx:apply | 按任务清单执行代码实现 |
/opsx:sync | 将变更的规范合并回主规范库 |
/opsx:archive | 归档变更，清理工作区 |
Step 1：创建提案（/opsx:propose）
在项目根目录启动 Claude Code：
bash
claude输入：
bash
> /opsx:propose "为项目添加暗黑模式支持"Claude 会：
- 读取
AGENTS.md和openspec/specs/了解项目背景 - 在
openspec/changes/add-dark-mode/下生成：proposal.md— 为什么要做这个功能specs/— 需求规范（Delta 形式）design.md— 技术方案tasks.md— 可执行的任务清单
你可以逐条审查这些文件，确认 AI 理解正确。如果有偏差，直接修改 Markdown，AI 会按更新后的规范执行。
Step 2：执行实现（/opsx:apply）
确认规范无误后，输入：
> /opsx:applyClaude 会读取 tasks.md，逐项完成：
- 修改代码
- 运行测试
- 更新任务状态
如果在实现过程中发现设计不合理，你可以随时修改 design.md 或 tasks.md，然后重新执行 /opsx:apply，AI 会从中断处继续。
Step 3：归档（/opsx:archive）
功能完成后：
> /opsx:archiveOpenSpec 会：
- 将
changes/add-dark-mode/specs/合并到openspec/specs/（更新 Source of Truth） - 将变更目录移动到
openspec/changes/archive/ - 清理工作区
七、进阶：让规范成为项目资产
1. 强制 AI 读取规范
在 VS Code 插件（如 Cline、Continue）中使用时，可以在对话开头要求：
在开始之前，请先阅读以下项目规范文件：
1. 项目根目录的 AGENTS.md
2. openspec/specs/ 目录下的所有 .md 规范文件
阅读完成后，请基于这些规范来回答我的问题。2. 配置自动读取（Cline）
在项目根目录创建 .clinerules 文件：
# 项目规范
你必须在每次回答前，先阅读 openspec/specs/ 和 AGENTS.md 了解项目背景。
当前活跃提案在 openspec/changes/ 目录下。Cline 每次对话会自动读取，无需手动 prompt。
3. 多工具协作
OpenSpec 支持 30+ 种 AI 工具。你可以在同一个项目里为 Claude Code、Cline、Continue 同时生成配置，规范文件是共享的，各工具的斜杠命令独立。
八、使用 OpenSpec 的好处
表格
| 维度 | 好处 |
|---|---|
| 对齐成本 | 需求在 Markdown 里，AI 不会”忘”，不用每次重复解释 |
| 可追溯性 | 每个变更都有 proposal.md → tasks.md → 代码的完整链路，Code Review 时可以审规范 |
| 防幻觉 | Delta 标记（ADDED/MODIFIED/REMOVED）让 AI 明确知道改什么、不改什么 |
| 低侵入 | 纯 Markdown，无数据库，无服务端，不绑定模型，随时可停用 |
| Brownfield 友好 | 特别适合在已有项目上迭代，不是只能从零开始 |
| 零额外成本 | OpenSpec 本身不调用 LLM，不消耗 API 额度 |
九、总结
OpenSpec 不是又一个 AI 编程工具，而是一套让 AI 编程”有章可循”的轻量框架。它不改变你使用 Claude Code 的习惯，只是在你和 AI 之间加了一层”规范契约”：
先对齐 Spec，再动手 Code。
对于个人开发者，它能防止 AI 改着改着跑偏；对于团队协作，它让 AI 的行为可审计、可复现。如果你已经用 Claude Code 写代码，花 5 分钟 npm install -g @fission-ai/openspec + openspec init，就能让 AI 从”vibe coding”进化到”规范驱动开发”。
参考链接
- OpenSpec GitHub: https://github.com/Fission-AI/OpenSpec
- Claude Code 官方文档: https://docs.anthropic.com/en/docs/claude-code/overview
