openspec基础实战

一、项目安装

1.1、安装依赖

# 全局安装
npm install -g @fission-ai/openspec@latest
# 校验版本
openspec --version

1.2、 项目初始化

# 交互式初始化（选择集成Cursor/Claude/opencode等）
openspec init

初始化生成目录：

openspec/
├─ specs/          # 项目永久规范基线（系统事实源）
└─ changes/
   ├─ [change-name]/  # 开发中变更目录
   └─ archive/     # 已归档完成需求
└─ AGENTS.md    #AI 配置

二、OpenSpec命令

OpenSpec 分Core 默认快速流程（极简 4 步） 、**Expanded 扩展全流程（团队复杂项目）**两类。

2.1、Core 命令

OpenSpec 安装后的默认模式，提供 4 个命令：

|---------------|-------------------|
| 命令 | 用途 |
| /opsx:explore | 开发前梳理思路 |
| /opsx:propose | 一步创建变更 + 生成全部规划制品 |
| /opsx:apply | 执行任务、编写代码 |
| /opsx:archive | 归档已完成的变更 |

工作流程

流程链路- 小型需求**：**

需求探索  →    创建变更 & 生成规范 → 编码落地 → 归档闭环
/opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive

阶段 1：explore 需求探索

/opsx:explore "需求描述：新增用户JWT登录，账号密码校验、异常拦截"

作用：需求模糊、调研技术方案。仅对话梳理需求，不生成任何项目文件，用来澄清边界、技术选型调研。

阶段 2：Propose 创建变更

/opsx:propose user-login "新增用户JWT登录功能，数据库存储账号、密码加密存储"

自动在changes/user-login/生成 4 个核心文件：

• proposal.md：需求目标、业务价值
• specs/：功能约束、入参出参、边界用例（项目规范源）
• design.md：架构、数据库、接口方案
• tasks.md：拆分可落地编码任务清单

作用：生成全套设计文档

阶段 3：Apply 落地编码

/opsx:apply user-login

作用：AI 按规范写代码。AI严格依照 specs+design 约束逐个完成 tasks 任务编码，禁止超范围开发，规避 AI 幻觉乱加功能。

阶段 4：Archive 归档

/opsx:archive user-login

作用：功能验收完成，闭环。自动先执行 sync 合并规范，再将changes/user-login移入归档目录，正式完成需求生命周期。

2.2、Expanded 命令解析

|--------------------|----------|------------------------|
| 命令 | 核心功能 | 一句话总结 |
| /opsx:new | 创建变更脚手架 | 只建目录，不生成制品 |
| /opsx:continue | 逐步创建制品 | 按依赖关系生成下一个制品 |
| /opsx:ff | 快速生成所有制品 | 一步到位，类似 core 的 propose |
| /opsx:verify | 验证实现 | 检查代码和规格是否一致 |
| /opsx:sync | 同步规格 | 把增量规格合并到主规格 |
| /opsx:bulk-archive | 批量归档 | 一次归档多个变更 |
| /opsx:onboard | 引导式教程 | 用实际代码库学习完整流程 |

完整链路：

新建变更→全量生成文档→迭代完善→编码→校验→同步→批量归档 
/opsx:new → /opsx:ff → /opsx:continue → /opsx:apply → /opsx:verify → /opsx:sync → /opsx:bulk-archive

斜杠命令	作用
/opsx:new order-pay "订单支付对接微信"	空目录新建变更脚手架，只创建文件夹不生成内容
/opsx:ff order-pay	FullFill 一键自动生成全套 spec/design/tasks
/opsx:continue order-pay	分步生成文档，分步评审，精细化管控
/opsx:verify order-pay	对照 spec 校验代码合规性、检查实现是否偏离约定
/opsx:bulk-archive	批量归档多个已完成变更
/opsx:edit order-pay	手动修订规范文档，锁定约束后再编码

三、目录结构

openspec/
├── AGENTS.md              # AI助手使用指南（自动生成）
├── project.md             # 项目专属上下文（技术栈、编码规范）
├── specs/                 # 权威基准：当前已部署的功能
│   └── [capability]/
│       ├── spec.md        # 需求说明与场景描述
│       └── design.md      # （可选）技术实现模式
├── changes/               # 提案集：进行中的工作
│   ├── [change-name]/
│   │   ├── proposal.md    # 提案背景、内容与影响评估
│   │   ├── tasks.md       # 实现任务清单
│   │   ├── design.md      # （可选）架构决策
│   │   └── specs/         # 增量规格说明
│   └── archive/           # 已完成变更的历史归档
└── config.yaml            # 项目配置（可选）

位置 : openspec/changes/[change-name]/

Artifact	路径	说明
proposal	proposal.md	需求目标、业务价值项目背景、变更范围、
design	design.md	架构、数据库、接口方案，架构决策表、视觉主题、风险与权衡
specs	specs/*/spec.md	功能约束、入参出参、边界用例（项目规范源）Given/When/Then格式
tasks	tasks.md	拆分可落地编码任务清单

四、终端 CLI 管理命令

1. 变更 & 规范查看

# 查看所有进行中变更+任务完成进度
openspec list
# 查看全项目所有spec基线
openspec list --specs
# JSON格式输出（CI流水线集成）
openspec list --json
# 查看单个变更详情（提案+规范+任务）
openspec show user-login
# 校验变更文档格式合法性
openspec validate user-login
# 快速查看项目仪表盘（交互式UI）
openspec view

2. 变更生命周期 CLI

# CLI手动新建变更
openspec new change user-refund
# CLI直接归档（-y跳过确认弹窗）
openspec archive user-refund -y
# 查看单个变更状态
openspec status --change user-refund

3. Schema 规范管理

# 列出全部可用规范模板
openspec schemas
# 查看指定schema来源路径
openspec schema which user-domain
# 安装shell命令自动补全
openspec completion install

五、应用场景

5.1、新项目从零开始

场景特点：新项目架构、方案需要技术负责人审核，需求分步细化，多轮迭代完善

1. 初始化项目（仅首次执行）

npm install -g @fission-ai/openspec
openspec init

2、 需求探索

/opsx:explore "新项目后台用户权限系统，包含角色管理、菜单权限、数据权限，需要适配后续多业务模块扩展"

3. 创建变更+生成初始方案

/opsx:propose system-permission "全局权限管理模块"
/opsx:ff system-permission

执行后生成：需求说明、架构设计、数据库设计、接口规范、任务清单（初稿）

4. 人工审核

人工阅读 changes/system-permission/ 下所有文档，判断方案是否可行，执行审核命令收口

# 人工审核：打开路径 openspec/changes/【变更名】 审阅4份md
# proposal.md(需求背景)、specs(验收标准)、design.md(技术方案)、tasks.md(开发任务)
/opsx:review system-permission

审核两种结果：

• 审核通过：直接进入编码阶段

• 审核驳回/需优化：进入方案迭代调整

5. 方案调整&循环迭代

适用：架构不合理、接口设计问题、需求补充、规则调整

逻辑：手动改本地 md 文档 → /opsx:ff → AI 依据修改内容全量刷新 proposal/spec/design/tasks（官方标准修改机制）

• /opsx:ff xxx：Fast-Forward，重读当前变更全部文档，联动刷新全份方案（改需求 / 改设计 / 改验收规则统一用它）

• /opsx:continue xxx：分步逐份刷新文档（精细微调场景，一次只更新一个文件）

  1、评审驳回→修改二选一

  方式A（简易快速）：本地直接修改对应md文件
  方式B（终端）：openspec edit 变更名
  #2、刷新整套方案（修改必执行）
  /opsx:ff 变更名
  #3、合规校验（可选）
  /opsx:validate 变更名

  循环：审阅→改文档→ff→再审阅，直到人工审核通过

执行效果：AI 增量修改spec/design/tasks，保留历史版本，不新建变更，可反复执行多次迭代

迭代完成后，再次执行人工审核，直至方案通过

6. 方案通过后编码落地

/opsx:apply system-permission

7. 编码后小迭代优化

适用：开发中发现细节需求偏差、逻辑优化

/opsx:ff system-permission "微调：优化权限校验拦截逻辑，增加空值异常处理"
/opsx:continue <变更名>
/opsx:apply system-permission

8. 收尾闭环

/opsx:verify system-permission
/opsx:sync system-permission
/opsx:archive system-permission

5.2、老项目加功能

老项目和新建项目不一样 - 代码已经存在，你未必了解每个细节，而且不能随意改动现有逻辑。OpenSpec 专门为这种情况设计了 Brownfield 工作流。核心区别在于：新项目可以直接 propose，老项目建议先 explore。

流程：探索 → 创建变更 → 实施 → 归档

# 1. 先探索：理解现有代码、不生成任何文件
/opsx:explore "给老项目添加【用户手机号登录】功能，不影响原有账号密码登录逻辑"

# 2. 创建变更（proposal）
/opsx:propose phone-login "新增手机号验证码登录功能"

# 3. 生成完整方案（spec + design + tasks）
/opsx:ff phone-login

# 4. 按规范编码（AI 只做允许的修改）
/opsx:apply phone-login

# 5. 校验代码是否符合规范（不破坏原有逻辑）
/opsx:verify phone-login

# 6. 同步规范到项目基线
/opsx:sync phone-login

# 7. 归档完成
/opsx:archive phone-login

5.3、老项目修 BUG

修 BUG 和加功能的工作流有个关键区别：粒度更小，重点在于精确定位问题行为。

# 1. 定位问题（explore 精准描述 BUG 行为）
/opsx:explore "BUG：用户支付成功后，订单状态没有更新，仍然显示待支付"

# 2. 创建修复变更
/opsx:propose fix-order-status "修复：支付成功后订单状态不更新"


# 3. 精准修复代码
/opsx:apply fix-order-status

# 4. 验证修复是否正确
/opsx:verify fix-order-status

# 5. 同步规范
/opsx:sync fix-order-status

# 6. 归档
/opsx:archive fix-order-status

5.4、并行变更

OpenSpec 有个实用的功能：多个变更可以并行进行。

比如你正在做 add-dark-mode，突然要修这个登录 BUG。不用放弃暗黑模式的进度：

#正在做 add-dark-mode，突然要修这个登录 BUG。不用放弃暗黑模式的进度
/opsx:new fix-login-redirect
#创建新变更，快进生成所有工件
/opsx:ff
#完成修复和归档后，回到暗黑模式继续
/opsx:apply add-dark-mode

5.5、需求修改、方案调整、迭代优化

1、手动打开：openspec/changes/my-feature/proposal.md，修改需求 / 变更内容
2、#刷新整套文档
/opsx:ff my-feature