OpenSpec CLI 与 OPSX 工作流说明

OpenSpec 不是服务端应用，而是一个面向 Spec-Driven Development 的本地 CLI + AI slash command 工作流工具。

它的核心思想是：

使用代码仓库中的 openspec/ 目录作为"规范数据库"，让 AI 编程助手围绕规范进行规划、实现、校验、同步和归档，而不是直接根据临时对话盲目写代码。

OpenSpec 本体通过终端命令 openspec 工作，负责项目初始化、AI 工具指令生成、规范校验、状态查看、变更归档等；而 /opsx:* 是注入到 AI 编程工具中的 slash commands，由 AI 编程助手根据这些命令执行具体的探索、规划、实现和验证流程。

1. 核心目录结构

初始化后（openspec init），项目中会出现 openspec/ 目录。典型结构如下：

xml 复制代码

openspec/
├── specs/
│   └── <domain>/
│       └── spec.md
├── changes/
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/
│           └── <domain>/
│               └── spec.md
└── config.yaml

其中：

路径	含义
`openspec/specs/`	主规格目录，是当前系统行为的事实来源
`openspec/changes/`	进行中的变更目录，每个变更一个独立子目录
`openspec/changes/<change-name>/proposal.md`	描述为什么做、要做什么、影响范围是什么
`openspec/changes/<change-name>/specs/`	增量规格，描述本次变更对主规格的新增、修改或删除
`openspec/changes/<change-name>/design.md`	技术设计、架构决策、实现方案
`openspec/changes/<change-name>/tasks.md`	可执行任务清单
`openspec/changes/archive/`	已完成变更的归档目录

OpenSpec 的关键点在于：

specs/ 描述系统当前真实行为，changes/ 描述正在提议或实现的变更；当变更完成后，delta specs 会合并回主规格目录。

2. CLI 命令与 OPSX Slash Commands 的区别

2.1 终端 CLI：`openspec`

openspec 是在 shell 中执行的命令，主要用于项目管理、校验、归档、配置和 AI 工具集成。

常见命令包括：

CLI command	作用
`openspec init`	初始化 OpenSpec 项目结构，并生成 AI 工具所需的指令文件
`openspec update`	升级或重新生成 AI 工具指令文件
`openspec list`	查看当前 changes 或 specs
`openspec show <item>`	查看某个 change 或 spec
`openspec validate`	校验 specs 或 changes 是否存在问题
`openspec status`	查看 artifact 进度
`openspec archive <change-name>`	完成变更归档，合并 delta specs 并移动 change 到 archive
`openspec config profile`	配置可用工作流 profile
`openspec instructions`	获取面向 agent 的下一步操作指令

2.2 AI Slash Commands：`/opsx:*`

/opsx:* 不是 shell 命令，而是在 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编程工具中输入的命令。

它们的作用是让 AI 编程助手按照 OpenSpec 规范执行工作流，例如：

bash 复制代码

/opsx:propose
/opsx:apply
/opsx:sync
/opsx:archive
/opsx:new
/opsx:continue
/opsx:ff
/opsx:verify

可以简单理解为：

类型	执行位置	面向对象	核心职责
`openspec` CLI	终端	人 / 脚本 / Agent	初始化、校验、查看、配置、归档、管理
`/opsx:*`	AI 编程助手对话界面	AI Agent	探索、生成规划制品、实现代码、验证实现、同步规格

3. 核心模式工作流

3.1 适用场景

核心模式适合：

需求已经比较清晰；
功能规模较小或中等；
希望快速从需求进入实现；
不需要逐个审查每个 artifact；
主要追求轻量、高速、低仪式感。

默认 core profile 的快速路径是：

bash 复制代码

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

同时也可以在需求不清晰时先使用 /opsx:explore。

3.2 核心模式命令

command	description
`/opsx:explore`	需求模糊时使用。AI 先分析问题、阅读代码、梳理思路、比较方案，必要时进行技术可行性调研。该阶段通常不直接创建规划制品。
`/opsx:propose`	需求清晰时使用。AI 一次性创建 change 目录，并生成规划制品，包括 `proposal.md`、delta specs、`design.md`、`tasks.md`。
`/opsx:apply`	执行具体变更。AI 读取 `tasks.md`，逐项实现代码、运行测试，并更新任务状态。
`/opsx:sync`	将当前 change 中的 delta specs 合并到主规格 `openspec/specs/`，但不归档 change。适合长期变更、并行开发或希望提前同步主规格的场景。
`/opsx:archive`	功能完成后收尾归档。必要时提示 sync，将变更合并进主规格，并把 change 移动到 archive。

3.3 核心模式状态流转

3.4 核心模式产物关系

bash 复制代码

需求输入
  ↓
/opsx:propose
  ↓
openspec/changes/<change-name>/
├── proposal.md
├── specs/
├── design.md
└── tasks.md
  ↓
/opsx:apply
  ↓
代码实现 + 测试验证 + tasks.md 更新
  ↓
/opsx:sync
  ↓
openspec/specs/ 更新
  ↓
/opsx:archive
  ↓
openspec/changes/archive/<date>-<change-name>/

4. 扩展模式工作流

4.1 适用场景

扩展模式适合：

复杂项目；
高风险变更；
架构调整；
需要逐步审查每个 artifact；
希望清晰控制 proposal、specs、design、tasks 的生成顺序；
希望在实现后增加独立验证环节；
多人协作或长期运行的变更。

扩展模式需要启用对应 workflow profile。通常通过以下命令选择并更新：

arduino 复制代码

openspec config profile
openspec update

扩展模式提供 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify 等更细粒度命令。

4.2 扩展模式命令

command	description
`/opsx:explore`	可选。需求不清晰时，先让 AI 分析问题、调查现有代码、比较技术路线。
`/opsx:new`	创建变更脚手架，只创建 change 目录和元数据文件，不自动生成完整规划制品。
`/opsx:continue`	根据 artifact 依赖图，逐步创建下一个 ready artifact。一次生成一个 artifact，适合逐步审查。
`/opsx:ff`	Fast-Forward。当需求明确时，按依赖顺序一次性生成所有 planning artifacts。
`/opsx:apply`	执行具体变更。AI 读取 `tasks.md`，逐条实现代码、运行测试，并更新任务状态。
`/opsx:verify`	从完整性、正确性、一致性等维度校验实现是否匹配规格意图。
`/opsx:sync`	手动提前将 delta specs 合并到主规格，不归档 change。适合长期变更和并行开发。
`/opsx:archive`	完成变更归档。必要时进行 sync，然后移动 change 到 archive。
`/opsx:bulk-archive`	可选扩展命令。用于一次性归档多个已完成变更。
`/opsx:onboard`	可选扩展命令。用于引导式学习和项目上手。

4.3 扩展模式状态流转

5. Artifact 依赖关系

OpenSpec 的核心不是"写一堆文档"，而是通过 artifact 依赖关系，让 AI 的实现过程有清晰上下文。

典型依赖关系如下：

bash 复制代码

proposal.md
  ↓
delta specs
  ↓
design.md
  ↓
tasks.md
  ↓
implementation
  ↓
verify
  ↓
sync / archive

更具体地说：

artifact	作用	依赖
`proposal.md`	描述变更意图、背景、范围、目标、非目标	用户需求
`specs/`	描述需求层面的行为变化，通常包含 ADDED / MODIFIED / REMOVED requirements	`proposal.md`
`design.md`	描述技术方案、架构决策、权衡和实现策略	`proposal.md` + `specs/`
`tasks.md`	将设计拆解为可执行任务清单	`proposal.md` + `specs/` + `design.md`
implementation	根据 `tasks.md` 实现代码	所有 planning artifacts
verification	校验实现是否满足规格意图	specs + design + tasks + code
archive	合并规格并归档变更	完成后的 change

6. 核心模式与扩展模式对比

维度	核心模式	扩展模式
目标	快速完成清晰需求	精细控制复杂变更
入口命令	`/opsx:propose`	`/opsx:new`
探索阶段	可选 `/opsx:explore`	可选 `/opsx:explore`
artifact 生成方式	一次性生成	分阶段生成或 fast-forward
规划节奏	快	可控
审查粒度	粗粒度	细粒度
实现命令	`/opsx:apply`	`/opsx:apply`
验证命令	可通过测试和人工审查完成	推荐 `/opsx:verify`
规格同步	`/opsx:sync`	`/opsx:sync`
收尾归档	`/opsx:archive`	`/opsx:archive`
适合场景	小功能、明确需求、快速迭代	架构变更、复杂需求、长期变更、多人协作

7. 推荐使用方式

7.1 需求明确的小功能

bash 复制代码

/opsx:propose add-login-rate-limit
/opsx:apply
/opsx:sync
/opsx:archive

适合：

增加一个简单功能；
修复明确 bug；
修改范围较小；
不需要逐个审查 artifact。

7.2 需求模糊，需要先调研

bash 复制代码

/opsx:explore
/opsx:propose optimize-page-load
/opsx:apply
/opsx:sync
/opsx:archive

适合：

不知道瓶颈在哪里；
不确定方案优劣；
需要 AI 先阅读代码、分析现状；
需要从探索结论自然过渡到正式 change。

7.3 复杂功能，逐步审查

bash 复制代码

/opsx:new add-payment-refund-flow
/opsx:continue
/opsx:continue
/opsx:continue
/opsx:continue
/opsx:apply
/opsx:verify
/opsx:sync
/opsx:archive

适合：

涉及多个模块；
需要人工审查 proposal、specs、design、tasks；
希望每一步都能停下来确认；
适合高风险业务功能。

7.4 复杂但需求清晰，希望快速生成全部规划制品

bash 复制代码

/opsx:new add-user-permission-system
/opsx:ff
/opsx:apply
/opsx:verify
/opsx:sync
/opsx:archive

适合：

需求已经比较清楚；
但仍希望使用扩展模式的结构化 workflow；
不想逐个 artifact 慢慢生成；
希望保留 /opsx:verify 的独立验证环节。

7.5 长期变更或并行开发

bash 复制代码

/opsx:new refactor-agent-runtime
/opsx:ff
/opsx:apply
/opsx:sync
/opsx:apply
/opsx:verify
/opsx:archive

适合：

一个 change 持续时间较长；
中途已有部分规格稳定下来；
多个开发者或多个 AI 会话并行工作；
希望提前把稳定的 delta specs 合并到主规格，减少上下文漂移。

8. 关键原则

8.1 `openspec/specs/` 是事实来源

openspec/specs/ 描述系统当前已经生效的行为。

AI、开发者、测试人员都应以它作为理解系统能力和边界的基础。

8.2 `openspec/changes/` 是变更工作区

每个 change 是一次独立的需求变更、功能开发、修复或重构。

它包含该变更所需的所有上下文：

复制代码

proposal.md
specs/
design.md
tasks.md

这样做的好处是：

变更上下文不会散落在聊天记录里；
AI 可以反复读取稳定的 artifact；
人可以审查、修改、提交到 Git；
长期项目中可以避免领域定义漂移。

8.3 先规格，后实现

OpenSpec 的核心不是"让 AI 更快写代码"，而是：

先让 AI 和开发者对需求、边界、设计、任务达成一致，再进入代码实现。

这可以降低以下风险：

AI 误解需求；
实现偏离业务意图；
多轮对话后上下文漂移；
代码完成了但规格没有沉淀；
后续维护者不知道当初为什么这么设计。

8.4 实现过程中允许更新 artifact

OpenSpec 不是一次性瀑布流程。

实现过程中如果发现原设计不合理，可以回头更新 proposal.md、specs/、design.md 或 tasks.md。

更合理的理解是：

复制代码

artifact 不是静态文档，而是变更过程中的结构化上下文。

8.5 Archive 不是简单移动目录

归档阶段通常包含：

检查 change 是否完成；
检查 tasks 是否完成；
检查 delta specs 是否需要合并；
将 delta specs 合并到 openspec/specs/；
将 change 移动到 openspec/changes/archive/；
保留变更历史，形成可追溯记录。

归档完成后：

bash 复制代码

openspec/specs/

成为新的事实来源，而：

bash 复制代码

openspec/changes/archive/

保存历史变更记录。

9. 总结

OpenSpec 可以理解为一套面向 AI 编程时代的轻量级规格管理机制。

它不是服务端系统，也不是传统需求管理平台，而是把规格、设计、任务、实现、验证和归档都放回代码仓库中，通过 CLI 和 AI slash commands 协同完成。

核心模式强调速度：

bash 复制代码

/opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive

扩展模式强调控制：

bash 复制代码

/opsx:new → /opsx:continue 或 /opsx:ff → /opsx:apply → /opsx:verify → /opsx:sync → /opsx:archive

最终目标是：

让 AI 不只是"会写代码"，而是始终围绕明确、可审查、可演进、可归档的规格来工作。

OpenSpec CLI 与 OPSX 工作流说明

1. 核心目录结构

2. CLI 命令与 OPSX Slash Commands 的区别

2.1 终端 CLI：openspec

2.2 AI Slash Commands：/opsx:*

3. 核心模式工作流

3.1 适用场景

3.2 核心模式命令

3.3 核心模式状态流转

3.4 核心模式产物关系

4. 扩展模式工作流

4.1 适用场景

4.2 扩展模式命令

4.3 扩展模式状态流转

5. Artifact 依赖关系

6. 核心模式与扩展模式对比

7. 推荐使用方式

7.1 需求明确的小功能

7.2 需求模糊，需要先调研

7.3 复杂功能，逐步审查

7.4 复杂但需求清晰，希望快速生成全部规划制品

7.5 长期变更或并行开发

8. 关键原则

8.1 openspec/specs/ 是事实来源

8.2 openspec/changes/ 是变更工作区

8.3 先规格，后实现

8.4 实现过程中允许更新 artifact

8.5 Archive 不是简单移动目录

9. 总结

2.1 终端 CLI：`openspec`

2.2 AI Slash Commands：`/opsx:*`

8.1 `openspec/specs/` 是事实来源

8.2 `openspec/changes/` 是变更工作区