OpenSpec 调研与使用指南

CharAznable
0 阅读4分钟

OpenSpec 调研与使用指南

一、OpenSpec 是什么

OpenSpec 是一套面向 AI 的规范驱动开发工作流：把「要做的事」拆成提案（proposal）→ 规范（specs）→ 设计（design）→ 任务（tasks） 等结构化文档，由 Cursor 等 AI 按规范生成与执行实现，并在完成后归档到主 specs，形成可复用的能力基线。

  • 官网与仓库：GitHub - Fission-AI/OpenSpec
  • 在本项目中的价值：
    • 需求先落成「可测试的规范」再写代码，减少理解偏差与返工
    • 变更可追溯：每个改动都有对应的 proposal / design / specs / tasks
    • 与 Cursor 深度集成：通过斜杠命令（/opsx:propose、/opsx:apply 等）一键生成文档并驱动实现
    • 归档后主 specs 持续积累，便于新成员或新需求时复用与约束

二、安装与初始化

安装 CLI

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

在项目中初始化

openspec init
  • 出现编辑器选择时，选 Cursor 并回车。

选择 Cursor

  • 初始化完成后，项目根目录下会生成 openspec/ 目录（内含 changes/、specs/ 等），并注册 Cursor 可用的 OpenSpec 斜杠命令。

生成 openspec 文件夹

openspec 目录结构

三、标准流程概览

阶段产出说明
提案proposal.md为什么要做、做多大、影响范围；定义 New/Modified Capabilities
规范specs/<能力名>/spec.md从「外部行为」描述能力应如何表现；含可测试的 Requirement / Scenario
设计design.md内部怎么实现（架构、技术选型、风险与回滚）
任务tasks.md具体要干哪些活、可勾选执行（apply 阶段按此推进）
实施代码变更在 Cursor 中执行 /opsx:apply <变更名>，按 tasks 逐项实现
验证检查与测试/opsx:verify <变更名> 做验收
归档主 specs + 归档目录/opsx:archive <变更名> 将能力合并进主 specs，变更移入 openspec/changes/archive/

用 OpenSpec 做一件事，本质是：先把你说的「需求+背景」拆成上述 4 类文档，再让 AI 按 tasks 落地实现并验证、归档。

四、Cursor 中的使用方式

在 Cursor 对话里输入 / 即可看到已注册的 OpenSpec 命令，例如：

  • /opsx:propose — 新建变更并生成 proposal / design / specs / tasks
  • /opsx:apply — 按 tasks 实施变更
  • /opsx:verify — 验证变更（规范校验 + 自定义验收）
  • /opsx:archive — 归档已完成的变更

Cursor 斜杠命令列表

五、示例 1：global-val 批量与缓存优化

背景与目标

  • 背景：接口 sys/config/global-val/get-val 支持多 key 逗号拼接（如 x,y,z）一次返回；项目内多处单独调用 getGlobalVal(key) 或 store.dispatch('config/getGlobalVal', key)，同一阶段对同一批 key 会发多次请求。
  • 目标：减少请求次数（合并 + 复用缓存），不改变调用方式与返回结构；通过预拉取 + 缓存 + 强制刷新白名单渐进式落地。

操作步骤

  1. 生成提案与规范
    在 Cursor 中输入： 
    /opsx:propose global-val-batching-and-cache
    并粘贴上述需求与背景，回车后会自动生成：
    • openspec/changes/global-val-batching-and-cache/
    • proposal.md、design.md、specs/ 下相关 spec、tasks.md

propose 输入需求与背景

生成对应需求规范文件夹

image.png

  1. 查看与验证
    • 终端查看当前变更：openspec list
    • 验证规范格式：openspec validate global-val-batching-and-cache
    • 若显示有效，可进入实施。

openspec list 查看变更

  1. 实施
    在 Cursor 中输入： 
    /opsx:apply global-val-batching-and-cache
    AI 会按 tasks.md 逐项实现并勾选完成。

执行 apply

  1. 验证 
    /opsx:verify global-val-batching-and-cache

验证成果

  1. 归档 
    /opsx:archive global-val-batching-and-cache
    归档时可按提示确认将能力合并进主 specs；归档后变更会移至 openspec/changes/archive/。

归档

归档完成

六、示例 2：Vue SCSS 样式移除错误 scope 属性

背景与目标

  • 问题：大量 Vue 文件的 <style lang="scss"> 被误写成带 scope 属性（正确应为 scoped）；scope 无效，样式隔离未生效，scss 均以全局加载。
  • 决策：现有业务已按全局 CSS 使用，不改为 scoped，而是批量移除所有 scss 标签中的 scope 属性，维持当前全局样式逻辑。

remove-scope 需求描述

操作步骤

  1. 生成提案 
    /opsx:propose remove-scope
    描述：批量移除 Vue 文件中 <style lang="scss"> 上的无效 scope 属性。
    生成变更目录：openspec/changes/remove-scope/，以及 proposal、design、specs、tasks。

已生成 remove-scope 变更提案

  1. 实施 
    /opsx:apply remove-scope
    按 tasks 实现脚本（如 scripts/remove-vue-style-scope.js）并执行批量修改；precheck 中可加入防回归检查。

apply 执行，检查已删除

apply 执行结果

  1. 验证 
    /opsx:verify remove-scope
    确认：无残留 scope、未误伤 scoped、脚本 dry-run 与 grep 复扫通过。

verify 验证结果

  1. 归档 
    /opsx:archive remove-scope
    建议使用 -y 非交互：openspec archive -y remove-scope，或按提示确认。归档后主 specs 中会新增/更新 vue-scss-style-scope-attr-removal 等能力描述。

archive 归档

archive 归档完成

七、常用命令速查

操作命令
列出当前变更openspec list
查看变更状态openspec status --change <变更名>
验证变更/规范openspec validate <变更名或 spec 名>
归档（非交互）openspec archive -y <变更名>

注意：斜杠命令中为 冒号，如 /opsx:apply、/opsx:verify、/opsx:archive，不要写成 opsx-apply。

文档优化：结构重组、术语统一、命令与路径代码化、补充「是什么」与「项目价值」、修正斜杠命令写法、增加速查表与注意事项。

备注

默认apply 指令会执行所有的task任务

如果想只执行某几条任务

则可以在对话框里面输入对应的任务条数

image.png

avatar
文章
阅读
粉丝