Claude Code + OpenSpec：让 AI 编码更可控的规范驱动开发

发表于 分类于 ， 阅读次数： 本文字数： 2.5k 阅读时长 ≈ 9 分钟

用 Claude Code 写代码久了，你可能会遇到这样的场景：一个需求聊着聊着就跑偏了，AI 理解的和你想要的总是差那么一点；或者一个复杂功能做到一半，上下文丢了，AI 又要重新理解一遍。

这种时候，你需要的不是更强的 AI，而是一套能让 AI “按规矩办事”的方法。OpenSpec 就是干这个的。

OpenSpec 是什么

简单说，OpenSpec 是一个规范驱动的开发工作流。它的核心思路是：在写代码之前，先把”要做什么”写清楚，让人和 AI 达成共识，然后再动手。

这不是什么新概念，但 OpenSpec 把它做成了一套轻量级的工具链，还针对 Claude Code、Cursor、Codex 等主流 AI 编码工具做了原生集成。

它能解决的问题：

  • 需求理解偏差：先写规范，AI 按规范实现，而不是凭空猜测
  • 复杂功能失控：把大功能拆成提案（proposal），每个提案有明确的任务列表
  • 上下文丢失：规范文件持久化存储，随时可以让 AI 重新读取
  • 多人协作：团队成员用不同的 AI 工具，但遵循同一套规范

几个核心命令

在开始之前，先简单了解下 OpenSpec 的命令，后面会在实际流程中用到：

  • openspec init：初始化项目，选择要集成的 AI 工具
  • openspec list：查看当前有哪些变更提案，加 --specs 可以看已有的规范
  • openspec validate：验证提案格式是否正确
  • openspec archive：把完成的提案归档，同时更新规范文件

命令不多，也不复杂。真正有意思的是它背后的工作流。

从零开始：初始化一个项目

假设你有一个现成的项目，想用 OpenSpec 来管理后续的开发。

1
2
3
4
5
6
7
8
# 全局安装
npm install -g @fission-ai/openspec@latest

# 进入项目目录
cd your-project

# 初始化
openspec init

运行 init 后，会出现一个交互式选择界面，让你选择要集成的 AI 工具。这里支持 20 多个工具，包括 Claude Code、Cursor、Codex、CodeBuddy、Cline 等等。

选择 Claude Code 后，它会生成这样一个目录结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
your-project/
├── openspec/
│   ├── project.md          # 项目描述文件
│   ├── AGENTS.md           # AI 工作流指令
│   ├── specs/              # 规范文件目录
│   └── changes/            # 变更提案目录
├── .claude/
│   └── commands/
│       └── openspec/
│           ├── proposal.md
│           ├── apply.md
│           └── archive.md
└── AGENTS.md               # 根目录的 AI 指令手册

这里有个关键点：它为 Claude Code 生成了三个 slash command。重启 Claude Code 后，你就可以用 /openspec:proposal、/openspec:apply、/openspec:archive 这三个命令了。

第一件事：让 AI 补完项目描述

初始化完成后，openspec/project.md 里只有一个基本框架。这时候可以让 Claude Code 来帮你填充：

1
帮我完善 openspec/project.md，描述一下这个项目的技术栈、架构和约定

Claude Code 会读取项目代码，然后帮你补全技术栈、目录结构、编码规范等信息。这个文件很重要，因为后续创建提案时，AI 会参考它来理解项目上下文。

同样的，如果你的项目已经有一些核心功能，也可以让 AI 帮你把现有功能整理成规范文件放到 openspec/specs/ 下。

正式开发：提案 → 实现 → 归档

假设现在要给项目加一个”用户资料搜索过滤”功能。按照传统做法，你可能直接说”帮我实现一个搜索过滤功能”，然后 AI 就开始写代码了。

但用 OpenSpec 的流程是这样的：

第一步：从需求到提案（这往往需要几轮对话）

需求到提案很少是一步到位的。实际情况通常是：你有个大概的想法，但细节还没想清楚；或者你觉得想清楚了，AI 理解的又是另一回事。

所以这一步的核心不是”一句话生成完美提案”，而是通过对话逐步澄清需求。

第一轮：抛出初步想法

1
我想给用户列表加个搜索过滤功能，你觉得需要考虑哪些点？

Claude Code 可能会问你：

  • 过滤条件有哪些？只按姓名搜，还是要支持多个字段？
  • 是前端过滤还是后端过滤？数据量大不大？
  • 过滤条件之间是”且”还是”或”的关系？
  • 需要保存用户的过滤偏好吗？

这时候你不需要马上有答案，可以边聊边想。比如你说”按姓名、部门、入职时间筛选，数据量不大，先做前端过滤”。

第二轮：细化场景

想法大致清楚后，可以让 AI 开始草拟提案：

1
/openspec:proposal 添加用户资料搜索过滤功能，支持按姓名、部门、入职时间筛选

Claude Code 会生成一套提案文件：

1
2
3
4
5
6
openspec/changes/add-profile-search-filter/
├── proposal.md
├── tasks.md
└── specs/
    └── user/
        └── spec.md    # 规范增量

但这只是初稿。看完之后你可能发现问题：

1
等等，部门筛选应该支持多选，一个人可能想同时看研发和产品两个部门的人

或者

1
入职时间筛选，是选一个具体日期，还是选一个时间范围？我想要的是范围

Claude Code 会根据你的反馈更新规范文件。

第三轮：确认边界情况

需求主体确认后，还要想想边界情况：

1
如果三个条件都填了，是同时满足才显示，还是满足任意一个就显示？
1
过滤结果为空的时候，页面怎么展示？
1
过滤条件要不要在 URL 里体现，方便分享链接？

这些问题有的你已经想好了，有的可能是 AI 帮你想到的。逐个确认后，提案才算真正完整。

为什么要这样做

这个过程看起来比”直接写代码”慢，但实际上省时间。

如果跳过讨论直接让 AI 实现，它会按自己的理解写。写完你发现”部门不支持多选”，改；改完发现”入职时间不是范围选择”，再改。每次改都要动代码，还可能引入 bug。

而在提案阶段讨论清楚，改的只是几行 Markdown。成本完全不一样。

第二步：审查和验证

几轮对话后，提案内容基本稳定了。这时候看一下生成的文件：

proposal.md 里会写清楚：

  • Why：为什么要做（比如”当前列表没有过滤能力，用户找人效率低”）
  • What Changes：具体改什么（新增三个过滤条件，调整列表展示逻辑）
  • Impact：影响哪些模块

tasks.md 里是任务清单，比如：

  • 1.1 添加过滤器组件
  • 1.2 实现姓名模糊搜索
  • 1.3 实现部门多选过滤
  • 1.4 实现入职时间范围过滤
  • 2.1 添加空结果提示
  • 2.2 将过滤条件同步到 URL

规范增量文件 specs/user/spec.md 里会用 ## ADDED Requirements 这样的标记，描述新增的能力和场景。

如果还需要微调，继续和 Claude Code 说：

1
任务列表里加一个"添加单元测试"，放在最后

确认无误后，跑一下验证：

1
openspec validate add-profile-search-filter --strict

通过了就可以进入实现阶段。

第三步：实现

提案确认没问题后：

1
/openspec:apply add-profile-search-filter

Claude Code 会读取提案，然后按照 tasks.md 里的清单逐项实现。每完成一项，它会把对应的 - [ ] 改成 - [x]。

这样做的好处是：即使中途上下文丢了，重新让 Claude Code 读取 tasks.md，它也能知道做到哪了。

第四步：归档

所有任务完成后：

1
/openspec:archive add-profile-search-filter

Claude Code 会执行 openspec archive add-profile-search-filter --yes，做两件事：

  1. 把 changes/add-profile-search-filter/ 移动到 changes/archive/2025-12-18-add-profile-search-filter/
  2. 把规范增量合并到 specs/user/spec.md

归档后，specs/ 下的规范就变成了”当前系统能力的完整描述”。下次再加新功能时，AI 读取规范就能知道系统现在能做什么。

什么时候不需要走这个流程

不是所有改动都要创建提案。官方给的建议是：

需要提案的：

  • 新功能、新能力
  • 会影响现有行为的改动
  • 架构调整
  • 破坏性变更

不需要提案的：

  • Bug 修复（恢复原本就该有的行为）
  • 文档更新、注释修改
  • 非破坏性的依赖升级
  • 简单的配置变更

这样既保持了流程的规范性，又不至于为了改个 typo 也要走一圈。

跨工具协作

OpenSpec 一个有意思的设计是：它不绑定特定的 AI 工具。

初始化时可以选多个工具，比如同时选 Claude Code 和 Cursor。这样团队里用不同工具的人，都能基于同一套规范工作。

而且因为规范文件是纯 Markdown，即使某个工具不在支持列表里，也可以手动让 AI 读取 openspec/AGENTS.md 来遵循工作流。

实际体验

用了一段时间，感觉 OpenSpec 适合这几种场景：

  1. 稍微复杂一点的功能开发：需要跨多个文件、涉及多个模块的功能，用提案来管理比较清晰
  2. 接手不熟悉的项目：先让 AI 把现有功能整理成规范，自己看规范比看代码快
  3. 团队协作：规范文件可以作为沟通的载体，新人看规范就能了解系统能力

不太适合的场景：

  • 纯探索性的原型开发，还没想清楚要做什么
  • 特别简单的改动，走流程反而累赘

最后

OpenSpec 的核心其实不是那几个命令，而是”先规范后实现”的思路。

这个思路本身不新，但当 AI 成为主要的代码编写者时，”让 AI 按规矩办事”就变得特别重要。毕竟 AI 不像人一样能靠直觉理解你没说出口的需求，把要求写清楚，它才能做得更准。

感兴趣的话，装上试试，从一个小功能开始体验这个流程。

项目地址：https://github.com/fission-ai/openspec