OpenSpec 简介以及学习教程

先问个问题：用 AI 写代码时，最怕什么？不是它写不好代码，而是它写完的东西跟你想要的完全不是一回事。

问题出在哪？需求只活在聊天记录里。AI 只知道你说了什么，不理解你真正在意什么。它根据一句话猜你的意图，结果猜出来的总差那么一点。

OpenSpec 就是为了解决这个问题而生的。

介绍

Spec-driven development——专门为 AI 编程助手设计的规范驱动开发框架。顾名思义，OpenSpec 的核心主张是：在写任何代码之前，先让“人”和“AI”同时明确一份 spec，然后按 spec 驱动实现。这相当于在你和 AI 之间加了一层轻量的 spec 层，双方协同的起点不是聊天记录，而是一份共用的、结构化、可追溯的规范说明。

这个框架的理念特别务实——拒绝僵化而鼓励流动，不是瀑布式流程而是不断迭代，追求轻量而非复杂，而且专门为已有项目设计，不只是面向新项目。

OpenSpec 的本质定位

AI 编程助手很强大，但当需求只活在聊天记录里时，一切都变得不可预测。OpenSpec 在中间加了这一层 spec，确保了“先对齐要构建什么”这个前提。

核心流程很简洁：

/opsx:new 
→ /opsx:ff（生成 proposal + specs + design + tasks）
→ /opsx:apply（实现）
→ /opsx:archive

其中 /opsx:ff 这一步，一次生成四类文档：

• proposal.md——做什么、为什么
• specs/——需求与场景（需求侧最核心的产出）
• design.md——技术方案
• tasks.md——实现清单

需求侧的应用方式

OpenSpec 可以当作需求-开发之间的桥接层，而不仅仅是开发者的规划工具。这里有四种切实可用的办法。

一、需求评审前用 /opsx:new 起草 proposal

产品或技术负责人在需求评审前，直接用 /opsx:new 创建变更目录，然后手写（或让 AI 辅助生成）proposal.md，把 why/what/scope 写清楚。这份文档可以直接当评审材料用——比传统 PRD 更结构化，最关键的是，后续它可以直接被 AI 拿去当作实现依据。

二、specs/ 目录承载业务验收标准

/opsx:ff 生成的 specs/ 目录是用来放 Given-When-Then 格式场景描述的。需求侧人员——产品、测试——可以在这里直接添加或修改验收条件。开发拿到的不是模糊的需求文档，而是可执行的场景：Claude Code 或 Cursor 这类工具可以参照这些场景直接生成测试用例。

三、brownfield 场景特别适合

OpenSpec 是为 brownfield（已有项目）而构建的，不是只考虑新项目。存量功能的改造——比如重构 TradeStateMachine、升级订单状态流转逻辑——这类需求，用 /opsx:new refactor-trade-state-machine 生成 spec 之后，新旧行为的差异可以在 specs/ 里显式描述出来，避免 AI 改出意料之外的后果。

四、团队协作场景：spec 作为沟通媒介

每个变更都有自己的目录，包含 proposal、specs、design 和 tasks。这个目录可以直接进 Git，前端、后端、测试、产品都能在同一份 spec 上做 review 和修改。需求的“契约”不再只停留在会议的沟通过程中，而是跟代码一起共生在仓库里。

一个具体的落地建议

OpenSpec 可以作为“需求侧到实现侧”全部打通的典型案例。整个链路是：

需求评审（产品）
↓
/opsx:new feature-name（创建 spec 目录）
↓
/opsx:ff（AI 生成 proposal + specs + design + tasks）
↓
需求侧 review specs/（产品 + 测试确认场景）
↓
/opsx:apply（Claude Code 按 spec 实现）
↓
测试按 specs/ 验收
↓
/opsx:archive

在这个链路中，/opsx:ff 之后、/opsx:apply 之前的 review 阶段，就是需求侧介入最自然的节点。

需求驱动

一个经典的失控场景

想象一下这个画面：你在做交易平台的订单状态重构。你打开 Claude Code，输入了一条指令：

帮我重构一下订单状态流转逻辑，现在状态太乱了

AI 开始工作。十分钟后，它改了 TradeStateMachine，顺手调整了 OrderServiceImpl，还把相关的枚举类重命名了。

乍看方向大致对，但细节上完全失去控制——状态流转的边界条件根本没覆盖你去确认过的那个“买家超时未确认”场景；重命名还破坏了另一个服务中对该枚举类的引用；而你原本最想要的那个“状态变更日志”功能，压根没有出现在输出中。

问题在哪？需求只活在聊天记录里。AI 根本没能力知道你真正在意什么边界条件，它只能靠那一句话猜测。

核心工作流：以订单状态重构为例

不妨用真实场景来一遍完整流程。

第一步：创建变更

/opsx:new refactor-trade-state-machine

Claude Code 会在 openspec/changes/refactor-trade-state-machine/ 下创建这个目录结构：

openspec/changes/refactor-trade-state-machine/
├── proposal.md   ← 为什么做这件事
├── design.md     ← 技术方案
├── tasks.md      ← 实现任务清单
└── specs/        ← 需求场景（最重要）
    └── trade-order/
        └── spec.md

第二步：快进生成所有规划文档

/opsx:ff

这一条命令让 Claude Code 读取你的现有代码，然后一气呵成生成四份文档。它会去扫描 TradeStateMachine.java、OrderServiceImpl.java、相关的枚举和 DTO，理解当前系统状态，再根据变更名称推断意图。

生成的 specs/trade-order/spec.md 大概长这样：

# trade-order Specification
## Purpose
管理游戏账号交易订单的完整生命周期，包括状态流转、超时处理和异常回滚。
## Requirements
### Requirement: 状态流转完整性
系统 SHALL 保证订单状态只能按照预定路径流转。
#### Scenario: 买家超时未确认
- GIVEN 订单处于"待买家确认"状态
- WHEN 超过 48 小时买家未操作
- THEN 系统自动将订单标记为"超时关闭"
- AND 触发退款流程
- AND 发送 RocketMQ 消息通知卖家
#### Scenario: 支付成功后的状态推进
- GIVEN 买家已完成支付
- WHEN 收到支付回调
- THEN 订单状态从"待支付"变更为"交易中"
- AND 记录状态变更日志到 trade_state_log 表

在 /opsx:apply 正式执行之前，你、产品、测试都可以直接 review 这份 spec.md。注意，这里写的是业务语言，不是代码。产品可以补充遗漏的场景，测试可以把验收条件直接追加进去，技术负责人可以确认边界条件。

这份文件一旦进了 Git，就是一份可追溯的需求契约。

第三步：review 并修改 spec

直接编辑 specs/trade-order/spec.md，把真正在意的场景补进去：

#### Scenario: 状态变更审计日志
- GIVEN 任意订单状态发生变更
- WHEN 状态流转执行
- THEN 向 trade_state_log 表写入一条记录
- AND 记录字段包含：操作人、原状态、新状态、时间戳、触发原因

这个补充动作不需要任何工具，就是写 Markdown。但它在下一步会直接影响 Claude Code 的实现行为。

第四步：按 spec 实现

/opsx:apply

Claude Code 读取 specs/ 里的所有场景，逐条执行 tasks.md 里的任务。每个任务完成后打勾，实现进度一目了然。

因为 spec 里已经明确写了“记录 trade_state_log”，Claude Code 会自动生成对应的实体类、Mapper、以及在状态流转节点插入日志的代码——而不是像之前那样只改了状态机就停了。

第五步：归档

/opsx:archive

变更目录移入 openspec/changes/archive/，与此同时 openspec/specs/trade-order/spec.md 被更新为最新的系统状态描述。这就是持久化的上下文：spec 和代码共同生活在仓库里，不会因为聊天窗口关闭而消失。

长期价值

随着功能迭代，openspec/specs/ 会逐渐积累成这样的结构：

openspec/specs/
├── trade-order/       ← 订单状态与生命周期
├── account-publish/   ← 账号发布审核流程
├── payment-callback/  ← 支付回调处理
├── recommend-feed/    ← 推荐流逻辑
└── user-auth/         ← 登录与权限

新人加入团队，读这个目录比读代码快得多——这里写的是系统“应该做什么”，而不是“当前怎么做的”。

下一次做相关功能时，Claude Code 启动就会读取已有的 spec，理解系统约束，不会提跟现有逻辑冲突的方案。

与 CLAUDE.md 的协同

OpenSpec 和 CLAUDE.md 是互补的：

• CLAUDE.md 定义的是项目级的永久约束：技术栈、代码规范、禁止行为
• OpenSpec specs/ 定义的是功能级的业务契约：每个能力应该做什么

在 CLAUDE.md 里加一行引用，就能让每次对话都感知到 spec：

## 业务规范
项目的功能规范定义在 openspec/specs/ 目录下。在实现任何涉及订单、账号、支付的功能前，先读取对应的 spec.md 文件。

这样即使不用 /opsx: 命令，Claude Code 在日常对话里也会主动去参考 spec 的约束。

给团队的建议

需求侧介入的最佳节点只有一处：/opsx:ff 之后、/opsx:apply 之前。

整个需求到实现的链路可以这样分工：

开发用 /opsx:new 和 /opsx:ff 生成 spec 草稿，产品在 specs/ 里确认业务场景并补充遗漏的边界条件，测试把验收标准直接写成 Given-When-Then 格式追加进去，然后提 PR review 这份 spec——通过之后才执行 /opsx:apply。

这个流程的核心变化是：需求评审的对象从 PRD 文档变成了 spec 文件，而 spec 文件直接就是 AI 的执行上下文。中间没有“翻译”环节，需求损耗降到最低。

需求生成

OpenSpec 官方 FAQ 明确回应过：他们正在探索从现有代码库生成 spec 的能力，但核心观点是——“试图一次性预先生成所有 spec 是浪费时间，应该按需创建并逐步积累”。

这不是回避问题，而是基于真实工程项目的判断。对一个人手上一两万行的 brownfield 项目，一次性逆向出完整的 spec 噪音极大，你根本不可能 review 完，更别说信任它的准确性。

但这不等于“不能从代码生成”，只是方法不同。目前有三条路可走。

/opsx:onboard（官方推荐入口）

对于已有项目，/opsx:onboard 命令会从你现有的代码库生成初始 spec，让 AI 从第一天就有项目上下文可以参考。

这是官方专门为 brownfield 场景设计的入口。它会扫描现有代码、理解项目结构，然后为核心能力生成初始 openspec/specs/ 文件。不是全量逆向，而是生成一个“够用的起点”。

在你的交易平台上执行这条命令，Claude Code 会读取 TradeStateMachine、GameAccountServiceImpl、支付回调相关代码，为每个主要能力域生成一份 spec 草稿，你再做 review 和修正。

需要知道的是，/opsx:onboard 被归入了“expanded workflow”。默认安装的 core profile 只包含四条命令：propose、explore、apply、archive。要使用 onboard，需要手动切换 profile 并更新。

具体操作：

openspec config profile
# 选择 expanded（包含 onboard）
openspec update
# 把新命令写入项目

之后 /opsx:onboard 就可以用了。

onboard 现在的实际功能

它是“引导式 onboarding”。流程是：扫描代码库找出改进机会，让你选一个小功能，走一遍完整的 propose → apply → archive 流程，大约 15 分钟。

注意这里需要纠正一个认知偏差：之前讨论的“从代码生成 spec 基线”，/opsx:onboard 实际上做的并不是这件事——它的核心目的是教新用户如何使用 OpenSpec，顺便扫描一次代码库找个练手素材，而不是系统性地逆向生成 openspec/specs/ 目录。

那 brownfield 冷启动怎么办：手动引导

官方的建议很务实：一次性预先生成所有 spec 是浪费时间，应该按需创建、边建边积累。

所以针对你的平台，最实际的策略还是那条路——直接对 Claude Code 下指令，按模块逐个生成：

请读取 src/trade/ 目录的代码，按照 openspec/specs//spec.md 的格式，
为订单状态管理这个能力域生成一份 spec，要求：
- 用 Given-When-Then 格式描述每个业务场景
- 只描述当前代码实际实现的行为，不要发明需求
- 按 Requirement → Scenario 层级组织
- 输出到 openspec/specs/trade-order/spec.md

一次只处理一个模块，半天能建起基线。这比跑一个工具然后 review 几百行自动生成内容要可控得多。

这种方式的好处很明显：你可以完全掌控颗粒度（一次只做一个模块），可以在 prompt 里注入业务语言约束，生成结果可以立即 review。

对 Spring Boot 项目来说，按服务边界逐个来就行：先 trade-order，再 account-publish，再 payment-callback，每次生成后 review 确认，整个过程大概半天能建立起有效的 spec 基线。

spec-gen（社区工具，专门做逆向）

社区里有人专门构建了一个叫 spec-gen 的开源 CLI 工具，通过静态分析结合 LLM 从现有代码库逆向工程出 OpenSpec 兼容的 spec。

它的三步流程是：

• spec-gen init（检测项目类型、创建配置）
• spec-gen analyze（静态分析，不需要 API Key）
• spec-gen generate（生成 OpenSpec 格式的 spec）