一篇文章带你入门OpenSpec

以下文字由个人语言组织编写所得，个人认为有些理论知识不应该是一大坨一大坨的文字让人望而却步，而应该是三言两语道出精妙

开篇

先整体了解下，有个宏观的知识

OpenSpec 1.0+引入了OPSX工作流，实现了动态指令体系

默认core配置

/opsx:propose ：一步创建变更并生成所有规划文档（proposal/design/specs/tasks）

/opsx:explore：进入探索模式，思考问题、调查代码库，不写代码

/opsx:apply：按照tasks.md实现任务，动态读取当前变更上下文

/opsx:archive：完成并归档当前变更，提示是否同步 Delta Spec到主规范

扩展工作流命令（通过openspec config profile开启）

/opsx:new：仅初始化变更目录结构（不创建文档）

/opsx:continue：按依赖顺序创建下一个文档（逐步模式）

/opsx:ff：快进生成所有规划文档（一步到位）

/opsx:verify：验证实现是否与规范一致

/opsx:sync：将Delta Spec 合并到主规范

/opsx:bulk-archive：批量归档多个已完成的变更

/opsx:onboard：15分钟全流程引导

OPSX工作流与旧版的最大区别在于：**动作而非阶段。**可以在任意时刻编辑任意文档，不存在阶段锁定。

为什么要用它？

回想下我们平时用AI进行编码对话，是不是都是直接跟AI对话发送提示词，我个人大部分时间也是这样，因为这样快爽，但是也对应着有不可控的风险，需要分场景使用，像一些小bug可以直接让其修复，那如果是做大功能呢？依旧对话的话就很容易你今天聊完明天就忘了聊了啥又或者你开了个新对话之前的记忆不记得了等等一些情况，OpenSpec就是解决这种问题的使其开发更加规范用我自己的话说其实就是先规划在执行编码，这样的好处就是AI编写的代码会更加准确幻觉减少，并且会沉淀出一些资源之后随时都能找到好复查复盘等。

核心快速路径

/opsx:propose ──► /opsx:apply ──► /opsx:archive

初始化

我用的是claude：openspec init --tools claude

产物：会创建出8个md文档和openspec目录看图

实践一

如果你还没想好做什么需求很模糊，获取你可以从它开始：

bash 复制代码
/opsx:explore
可以和它聊聊你想做什么？

它询问我要想探索什么，我这里就直接说学生导出什么做？

接着它会让你确定想要什么样的按需选择即可回复它

提案，生成规划文档

bash 复制代码

/opsx:propose 学生导出

产物：四个产物

产物内容

proposal.md（宏观意图）为什么做 + 影响范围

specs/student-export/spec.md（具体的接口定义与数据模型） 2 个 Requirement，6 个 Scenario

design.md（系统设计草案（架构图、数据流））技术方案（Blob 下载 + CSV 编码 + 复用筛选）

tasks.md（拆解后的开发任务） 10 个任务，分 4 组

.openspec.yaml不是产物，是 CLI 的元数据文件。就两行：
yaml 复制代码
schema: spec-driven
created: 2026-07-17
记录这个 change 用的 schema 类型和创建日期。你不用管它，CLI 自动维护的

产物	内容
`proposal.md`（宏观意图）	为什么做 + 影响范围
`specs/student-export/spec.md`（具体的接口定义与数据模型）	2 个 Requirement，6 个 Scenario
`design.md`（系统设计草案（架构图、数据流））	技术方案（Blob 下载 + CSV 编码 + 复用筛选）
`tasks.md`（拆解后的开发任务）	10 个任务，分 4 组

应用：执行任务清单

/opsx:apply

发送即可，接着它会执行任务，接着改代码完成之后会更新任务状态清单，页面如下我试过了能导出并且没数据的时候会提示：无数据可导出，我觉得做的还是不错的

归档

bash 复制代码
/opsx:archive

选第一个

立即同步（推荐）--将增量规范合并到openspec/specs/student export/spec.md中，然后存档
存档而不同步------只存档，规格保留在更改文件夹中

我这里就选1了

归档前后对比：

归档前：

arduino 复制代码

openspec/
├── changes/
│   └── export-students/          ← 活跃 change
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/
│           └── student-export/
│               └── spec.md       ← delta spec
└── specs/                        ← 空目录

归档后：

arduino 复制代码

openspec/
├── changes/
│   └── archive/
│       └── 2026-07-17-export-students/  ← 归档的 change
│           ├── .openspec.yaml
│           ├── proposal.md
│           ├── design.md
│           ├── tasks.md
│           └── specs/
│               └── student-export/
│                   └── spec.md   ← 保留副本
└── specs/
    └── student-export/
        └── spec.md               ← 新的 main spec（从 delta 同步）

至此，一个功能就完成了！

实践二

没想好做什么可以先跟它沟通，需求明确可以跳过这步，去到 new

/opsx:explore 我想加个教师管理

这一步主要是为了和AI确定好你想要的东西。

创建change空壳
/opsx:new 添加教师管理功能
- 会创建出一个changes
写第一个产物
/opsx:continue
- 产出物就一个，proposal.md 其实到这就已经跟上面操作的那种方式的区别显而易见了，上面/opsx:propose方式是一次性所有把产物都产出，这里则是一步步确认执行产出
剩余产物
继续执行 /opsx:continue
- 依次会得到 design.md、spec.md、tasks.md
插播一条

不能一次次continue的话也可以 /opsx:ff 快进生成所有规范文档一步到位这个我就不演示了
此时文档及任务清单都输出完全，可以进入执行阶段了 /opsx:apply
/opsx:apply
- 静候执行写代码... 写完代码会更新任务清单的
建议在归档之前加一步验证的操作，检查实现是否符合 spec
/opsx:verify
- 接着它会做一系列的验证，等候结果即可，此时它给我验出来了几个问题让它做掉
- 修复了缺陷，我接着继续让验证一遍
  - 可以看到这次都对齐了
功能这边我自行验证了没问题

最后归档即可
/opsx:archive
- 建议选立即同步