一篇文章带你入门OpenSpec

金金金__
109 阅读5分钟

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

开篇

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

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

安装

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

初始化

openspec init 然后会让你选择工具 你按需选择即可或者使用下方直接指定的方式

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

  • 产物：会创建出8个md文档和openspec目录 看图 image-20260717105528010-1784296292577.png image-20260717105537840.png

实践一

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

/opsx:explore

可以和它聊聊你想做什么？

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

image-20260717105409166.png

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

    image-20260717105836281-1784296383413.png

提案，生成规划文档

/opsx:propose 学生导出

产物：四个产物

image-20260717114341646.png

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

.openspec.yaml不是产物，是 CLI 的元数据文件。就两行：

schema: spec-driven
created: 2026-07-17

记录这个 change 用的 schema 类型和创建日期。你不用管它，CLI 自动维护的

应用：执行任务清单

/opsx:apply

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

image-20260717120638230.png 归档

/opsx:archive

选第一个

image-20260717121022013.png

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

我这里就选1了

归档前后对比：

归档前：

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

归档后：

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确定好你想要的东西。

image-20260717134738832.png

  • 创建change空壳

    /opsx:new 添加教师管理功能

    • 会创建出一个changes

    image-20260717135357514.png

  • 写第一个产物

    /opsx:continue

    • 产出物就一个，proposal.md 其实到这就已经跟上面操作的那种方式的区别显而易见了，上面/opsx:propose方式是一次性所有把产物都产出，这里则是一步步确认 执行 产出

    image-20260717135546655.png

  • 剩余产物

    继续执行 /opsx:continue

    • 依次会得到 design.md、spec.md、tasks.md

  • 插播一条

    不能一次次continue的话也可以 /opsx:ff 快进生成所有规范文档 一步到位 这个我就不演示了

  • 此时文档及任务清单都输出完全，可以进入执行阶段了 /opsx:apply

    /opsx:apply

    • 静候执行写代码... 写完代码会更新任务清单的

  • 建议在归档之前加一步验证的操作，检查实现是否符合 spec

    /opsx:verify

    image-20260717142509133.png

    • 接着它会做一系列的验证，等候结果即可，此时它给我验出来了几个问题 让它做掉 image-20260717142735581.png

    • 修复了缺陷，我接着继续让验证一遍 image-20260717143736070.png

      • 可以看到这次都对齐了

  • 功能这边我自行验证了没问题

image-20260717143855944.png

  • 最后归档即可

    /opsx:archive

    • 建议选立即同步 image-20260717143926815.png
avatar
文章
阅读
粉丝