Openspec

  |   0 评论   |   0 浏览

OpenSpec 详解

1. OpenSpec 说明

OpenSpec 是一个轻量级的规范驱动（spec-driven development）框架，专为 AI 编码助手设计。
核心理念：先写规范，再写代码。让 AI 在明确的"契约"下工作，避免模糊提示导致的需求偏移。

2. 安装与初始化

2.1 安装

OpenSpec 是一个 npm 包，支持全局安装。你需要先确保系统已安装 Node.js 20.19 或更高版本。

使用 npm 安装：

# 全局安装
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

使用 pnpm 安装：

pnpm add -g @fission-ai/openspec@latest

使用 yarn 安装：

yarn global add @fission-ai/openspec@latest

免安装直接使用（npx）：

npx @fission-ai/openspec@latest init

升级提示： 升级 CLI 后，记得在项目目录中运行 openspec update 来重新生成 AI 指导文件。

2.2 初始化

cd your-project
openspec-cn init

其他指令：

# 指定特定工具
openspec init --tools claude,cursor

# 支持所有工具
openspec init --tools all

# 跳过工具配置
openspec init --tools none

# 覆盖 profile
openspec init --profile core

# 自动清理旧配置
openspec init --force

3. 目录结构

目录结构

核心目录说明

specs/（规格）

系统行为的真实来源，按领域组织（如 auth/、payments/）。描述系统「现在」的行为。

changes/（变更）

每个变更提案独立一个文件夹，包含完整的规划产物。归档后增量规格会合并到 specs/。

4. 核心工作流

OpenSpec 采用四阶段工作流，通过斜杠命令在 AI 助手的聊天面板中操作：

工作流

OpenSpec 提供两种工作流模式：快速路径（默认 core profile）和扩展路径（自定义工作流）。

快速路径（Core Profile）

适合大多数场景，四步完成一个功能：

/opsx:propose（创建提案） → /opsx:apply（实施任务） → /opsx:sync（同步规格） → /opsx:archive（归档变更）

快速路径

完整演练：添加暗色模式

第 1 步：创建提案

在你的 AI 助手聊天界面中输入：

/opsx:propose 添加暗色模式支持

AI 会自动创建 openspec/changes/add-dark-mode/ 目录，并生成提案、规格、设计和任务文件。

第 2 步：审查提案

检查 AI 生成的文件，确认方向正确：

openspec show add-dark-mode
openspec status --change add-dark-mode

第 3 步：实施任务

让 AI 按任务清单逐项执行：

/opsx:apply

AI 会读取 tasks.md 中的任务，逐个完成并勾选。

第 4 步：同步并归档

实施完成后，同步规格并归档：

# 可选：先将增量规格合并到主规格
/opsx:sync

# 归档变更
/opsx:archive

归档会将增量规格合并到 openspec/specs/，并将变更移动到归档目录。

产物依赖关系

OpenSpec 的核心引擎是产物依赖图（Artifact Graph），定义了各产物之间的依赖关系：

产物依赖关系

产物状态： 每个产物有三种状态：

  • BLOCKED — 缺少依赖，不可创建
  • READY — 依赖已满足，可以创建
  • DONE — 输出文件已存在于文件系统中

状态通过检查文件系统自动检测。

5. 命令参考

AI 斜杠命令（在 AI 助手中使用）

这些命令在 AI 编程助手的聊天界面中输入，不是终端命令。

命令用途模式
/opsx:propose一步创建变更 + 所有规划产物Core
/opsx:explore探索想法、调查问题、澄清需求Core
/opsx:apply按 tasks.md 实施任务Core
/opsx:sync将增量规格合并到主规格Core
/opsx:archive归档变更，合并规格Core
/opsx:new创建新的变更脚手架扩展
/opsx:continue增量创建下一个就绪产物扩展
/opsx:ff快速创建所有规划产物扩展
/opsx:verify验证实施是否与产物一致扩展
/opsx:bulk-archive批量归档已完成的变更扩展
/opsx:onboard引导式交互教程扩展

注意： 不同 AI 工具的命令语法可能不同。例如 Claude Code 使用 /opsx:propose，而 Cursor 使用 /opsx-propose（用短横线替代冒号）。

终端 CLI 命令

这些命令在终端中运行。

类别命令用途
设置openspec init在项目中初始化 OpenSpec
openspec update重新生成 AI 指导文件
浏览openspec list列出变更或规格
openspec view交互式终端仪表盘
openspec show [item]显示变更或规格详情
验证openspec validate验证变更/规格
openspec status查看产物完成状态
生命周期openspec archive归档已完成的变更
openspec new change创建新的变更目录
配置openspec config list列出配置项
openspec config set设置配置值
openspec config profile切换工作流 Profile
Schemaopenspec schema init创建新的 Schema
openspec schema fork复制现有 Schema
openspec schema validate验证 Schema 结构

6. 支持的 AI 工具

支持的 AI 工具

如何工作：

OpenSpec 在每个 AI 工具的配置目录中安装 SKILL.md 文件和 opsx-<id>.md 命令文件。例如对 Claude Code，文件安装在 .claude/ 目录下；对 Cursor，安装在 .cursor/ 下。

7. 进阶用法

项目配置（config.yaml）

通过 openspec/config.yaml 可以自定义项目级行为：

# openspec/config.yaml
schema: spec-driven                 # 默认 Schema

context: |                           # 注入到所有产物指令中
  技术栈: TypeScript, React
  测试框架: Vitest

rules:                               # 按产物 ID 设置规则
  proposal:
    - 包含回滚计划
  specs:
    - 使用 Given/When/Then 格式

增量规格（Delta Specs）

增量规格描述相对于当前规格的变化，支持三种操作：

章节含义归档时行为
## ADDED Requirements新增行为追加到主规格
## MODIFIED Requirements修改行为替换现有需求
## REMOVED Requirements移除行为从主规格中删除

自定义 Schema

你可以创建自己的工作流 Schema 来定义不同的产物和依赖关系：

# 创建新 Schema
openspec schema init my-workflow

# 基于现有 Schema 创建
openspec schema fork spec-driven my-custom

# 切换到自定义 Schema
openspec config profile

Schema 解析优先级

  1. CLI 参数（最高） — --schema <name> 命令行参数直接指定
  2. 变更元数据 — 变更目录下的 .openspec.yaml 文件
  3. 项目配置 — openspec/config.yaml 中的设置
  4. 默认值（最低） — 使用内置的 spec-driven Schema

环境变量

变量用途
OPENSPEC_TELEMETRY=0禁用匿名遥测
DO_NOT_TRACK=1禁用遥测（标准 DNT 信号）
NO_COLOR=1禁用彩色输出
OPENSPEC_CONCURRENCY最大并行验证数（默认: 6）

8. 常见问题

OpenSpec 和传统的需求文档有什么区别？

OpenSpec 专为 AI 协作设计，不是给人看的需求文档。它结构化的 Markdown 格式让 AI 能精确理解上下文，并通过增量规格机制管理变化，而非维护庞大且容易过时的文档。

我需要重写现有代码吗？

不需要。OpenSpec 是棕地友好的，可以在任何现有项目中使用。你只需描述现有系统的行为（specs/），然后按需提出变更。

我必须按顺序完成所有产物吗？

使用快速路径（Core Profile）时，/opsx:propose 会一步生成所有产物。你只需要审查、实施和归档。如果想更精细地控制，可以切换到扩展路径。

增量规格合并时发生冲突怎么办？

/opsx:sync 命令会提示你处理冲突。你也可以使用 /opsx:bulk-archive 批量处理已完成的变更，系统会自动处理规格冲突。

如何禁用遥测？

设置环境变量 OPENSPEC_TELEMETRY=0 或 DO_NOT_TRACK=1。遥测只收集命令名称和版本号，不包含任何参数、路径、内容或个人信息。

在哪里获取帮助？

GitHub 仓库：https://github.com/Fission-AI/OpenSpec

一、先搞清楚：OpenSpec Skill 是什么

OpenSpec 是一套**规范驱动开发（Spec-Driven）**的 AI 工作流，靠 4 个核心 Skill（能力）完成功能迭代：

  • /opsx:explore 探索：理解现状、分析影响
  • /opsx:propose 提案：写需求、设计、任务
  • /opsx:apply 实施：按规范生成/修改代码
  • /opsx:archive 归档：把变更合并进主规格

工作流（迭代闭环）：

explore → propose → apply →（不满意→改 design →再 apply）→ archive

二、环境准备（1 分钟）

1. 安装（全局）

npm install -g openspec

验证：

opsx --version

2. 项目初始化（已有项目也能跑）

在项目根目录执行：

/opsx:init

会生成：

openspec/
├── specs/       # 系统当前规格（唯一可信源）
└── changes/     # 每次迭代的临时变更

三、第一次功能迭代（标准流程）

Step 1：探索现状（explore）

目的：让 AI 读懂现有代码 + 规格，避免重复/冲突。

/opsx:explore
  • AI 会扫描 openspec/specs/ 和项目代码
  • 输出：系统能力、模块依赖、可扩展点

Step 2：发起变更提案（propose）

目的：把"想法"变成可评审的需求 + 设计 + 任务。

/opsx:propose 新增暗黑模式切换

生成目录：

openspec/changes/add-dark-mode/
├── proposal.md  # 为什么改、改什么、影响范围
├── design.md    # 技术方案、架构、逻辑
├── tasks.md     # 拆分好的可执行任务
└── specs/       # 本次增量规格（delta spec）

Step 3：评审 & 修改（关键迭代点）

  • 打开 design.md：觉得方案不对 → 直接改
  • 打开 tasks.md：任务不合理 → 直接调
  • 不需要重新走流程，改完直接下一步

Step 4：实施代码（apply）

目的：AI 按最终 design + tasks 生成代码。

/opsx:apply
  • AI 逐任务执行：改配置、加组件、写逻辑
  • 全程对齐 design.md，不瞎发挥

Step 5：验证 & 回退（迭代核心）

  • 运行项目：功能正常 → 继续；有问题 → 回到 Step 3 改 design.md
  • 再执行 /opsx:apply → AI 会增量更新代码，不是重写
  • 可反复"改 design → apply"，直到满意

Step 6：归档（archive）

确认功能稳定、测试通过：

/opsx:archive
  • 把本次 changes/xxx/specs 合并到主 openspec/specs/
  • 归档变更记录到 changes/xxx/，留痕追溯
  • 主规格更新为系统当前真实行为，下次迭代以此为基准

四、第二轮迭代（在已有功能上叠加）

例子：已有"暗黑模式"，再加"跟随系统"选项。

  1. /opsx:explore → AI 读取已归档的暗黑模式规格
  2. /opsx:propose 暗黑模式增加跟随系统选项
  3. 评审 design.md → 调整触发逻辑
  4. /opsx:apply → 增量修改代码（不破坏旧功能）
  5. 验证 → 没问题 /opsx:archive

每次迭代都基于上一次归档后的主规格，形成稳定叠加闭环。

五、常用命令速查表（直接复制用）

# 初始化项目
/opsx:init

# 探索现状
/opsx:explore

# 发起功能提案
/opsx:propose 你的需求描述

# 实施代码
/opsx:apply

# 归档完成变更
/opsx:archive

# 查看所有变更
/opsx:list

六、关键注意点（避坑）

  1. 所有迭代都从 explore 开始：确保 AI 基于最新规格，不是旧记忆。
  2. 改方案只改 design.md：不要直接改代码，否则规格和代码不一致。
  3. apply 是增量的：反复执行只会更新差异，不会覆盖已正确的代码。
  4. archive 不可逆：归档后规格合并，不能回退本次变更，归档前务必验证。
标题：Openspec
作者：llp
地址：https://llinp.cn/articles/2026/05/12/1778544408451.html