OpenSpec入门教程：最新简介与实战指南
用 AI 写代码，最让人头疼的是什么？不是它写不出好代码，而是它产出的东西与你设想的完全对不上。
问题出在需求仅停留在聊天记录里。AI 只知道你说了什么，却无法理解你真正在意哪些细节。它根据一句话猜测意图，结果往往与目标差之毫厘、谬以千里。
OpenSpec 正是为此而生。
OpenSpec 核心概念
规范驱动开发——专为 AI 编程助手设计的框架。OpenSpec 的核心主张：在落笔写代码前，让“人”和“AI”同时对齐一份 spec，然后按 spec 驱动实现。这相当于在你和 AI 之间嵌入一个轻量的规范层，协作起点不再是聊天记录，而是一份共享的、结构化的、可追溯的规范说明。
框架理念非常务实：拒绝僵化，拥抱流动；不是瀑布式流程，而是持续迭代；追求轻量而非复杂性；且专门针对已有项目（brownfield）设计，并非仅限新项目。
OpenSpec 的核心定位
AI 编程助手功能强大，但一旦需求只存在于聊天记录里，一切就变得不可控。OpenSpec 在中间增加了这层规范，确保“先对齐要构建什么”这个前提得到满足。
核心流程极为简洁：
/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）