OPSX 工作流

欢迎在 Discord 上提交反馈。

它是什么？

OPSX 现已成为 OpenSpec 的标准工作流。

它是 OpenSpec 变更的灵活、迭代式工作流，不再有僵化的阶段划分——只有你可以随时执行的操作。

为何存在

旧版 OpenSpec 工作流可以运行，但存在僵化封闭的问题：

• 指令硬编码——藏在 TypeScript 代码深处，无法修改
• 全有或全无——单个大命令生成所有内容，无法单独测试各个模块
• 结构固定——所有人使用同一套工作流，无法自定义
• 黑盒操作——当 AI 输出效果差时，无法调整提示词

OPSX 打破了这些限制。 现在任何人都可以：

1. 试验指令效果——编辑模板，观察 AI 输出是否更优
2. 细粒度测试——独立验证每个产物的指令配置
3. 自定义工作流——自行定义产物和依赖关系
4. 快速迭代——修改模板后立即测试，无需重新构建

旧版工作流：                      OPSX：
┌────────────────────────┐           ┌────────────────────────┐
│  硬编码在包内  │           │  schema.yaml           │◄── 你编辑此文件
│  （无法修改）        │           │  templates/*.md        │◄── 或编辑此目录
│        ↓               │           │        ↓               │
│  等待新版本发布  │           │  立即生效        │
│        ↓               │           │        ↓               │
│  期望效果更好      │           │  自行测试效果      │
└────────────────────────┘           └────────────────────────┘

适用于所有人群：

• 团队——创建贴合实际工作流程的自定义工作流
• 高级用户——调整提示词，为你的代码库获得更优的 AI 输出
• OpenSpec 贡献者——无需发布新版本即可试验新方案

我们仍在探索最优方案，OPSX 让我们可以共同学习。

用户体验

线性工作流的问题： 你会经历「规划阶段」「实施阶段」「完成」的线性流程，但实际工作并非如此：你实施某个功能后，发现设计有误，需要更新规格说明，再继续实施。线性阶段与实际工作方式背道而驰。

OPSX 的解决思路：

• 以动作而非阶段为核心——创建、实施、更新、归档，随时可执行任意操作
• 依赖是赋能项而非强制项——它们仅展示当前可执行的操作，而非下一步必须做的事

  proposal ──→ specs ──→ design ──→ tasks ──→ implement

安装配置

# 确保已安装 openspec——技能会自动生成
openspec init

该命令会在 .claude/skills/（或对应目录）下生成技能文件，AI 编程助手会自动识别这些技能。

默认情况下，OpenSpec 使用 core 工作流配置（包含 propose、explore、apply、sync、archive 命令）。若需要使用扩展工作流命令（new、continue、ff、verify、bulk-archive、onboard），可通过 openspec config profile 配置，再执行 openspec update 生效。

安装过程中，系统会提示你创建项目配置（openspec/config.yaml），该配置可选但推荐创建。

项目配置

项目配置允许你设置默认参数，并将项目专属上下文注入到所有产物中。

创建配置

配置会在 openspec init 过程中自动创建，也可手动创建：

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format for scenarios
  design:
    - Include sequence diagrams for complex flows

配置字段

字段	类型	说明
schema	字符串	新变更的默认架构（例如 spec-driven）
context	字符串	注入到所有产物指令中的项目上下文
rules	对象	按产物ID分类的专属规则

工作原理

架构优先级（从高到低）：

1. CLI 参数（--schema <名称>）
2. 变更元数据（变更目录下的 .openspec.yaml）
3. 项目配置（openspec/config.yaml）
4. 默认值（spec-driven）

上下文注入规则：

• 上下文会被添加到每个产物的指令开头
• 用 <context>...</context> 标签包裹
• 帮助 AI 理解你项目的规范约定

规则注入规则：

• 规则仅注入到匹配的产物中
• 用 <rules>...</rules> 标签包裹
• 位于上下文之后、模板之前

各架构对应的产物ID

spec-driven（默认架构）：

• proposal — 变更提案
• specs — 规格说明
• design — 技术设计
• tasks — 实施任务

配置校验

• rules 中包含未知产物ID会触发警告
• 架构名称会与可用架构列表做校验
• 上下文大小限制为 50KB
• 无效 YAML 会附带行号报错

故障排查

「rules 中存在未知产物 ID：X」

• 检查产物 ID 是否与当前架构匹配（见上方列表）
• 执行 openspec schemas --json 可查看各架构对应的产物 ID

配置未生效：

• 确认文件路径为 openspec/config.yaml（而非 .yml 后缀）
• 使用校验工具检查 YAML 语法是否正确
• 配置修改会立即生效，无需重启

上下文过大：

• 上下文大小限制为 50KB
• 请对内容做摘要，或链接到外部文档

命令

命令	功能说明
/opsx:propose	一键创建变更并生成规划产物（默认快捷路径）
/opsx:explore	梳理思路、调研问题、澄清需求
/opsx:new	创建新变更脚手架（扩展工作流）
/opsx:continue	创建下一个产物（扩展工作流）
/opsx:ff	一次性生成所有规划产物（扩展工作流）
/opsx:apply	实施任务，按需更新产物
/opsx:update	修订变更的规划产物并保持内容一致性
/opsx:verify	对照产物校验实施结果（扩展工作流）
/opsx:sync	将增量规格同步到主分支（默认工作流，可选）
/opsx:archive	完成后归档变更
/opsx:bulk-archive	批量归档多个已完成的变更（扩展工作流）
/opsx:onboard	端到端变更的引导式演练（扩展工作流）

使用说明

探索想法

/opsx:explore

梳理思路、调研问题、对比方案，无需固定结构，仅作为你的思考伙伴。当思路清晰后，可切换到 /opsx:propose（默认工作流）或 /opsx:new//opsx:ff（扩展工作流）继续。

创建新变更

/opsx:propose

创建变更并生成实施前所需的全部规划产物。

若已启用扩展工作流，也可使用以下命令：

/opsx:new        # 仅创建脚手架
/opsx:continue   # 每次创建一个产物
/opsx:ff         # 一次性生成所有规划产物

创建产物

/opsx:continue

根据依赖关系展示当前可创建的产物，每次仅创建一个。可重复执行该命令，逐步完善你的变更。

/opsx:ff add-dark-mode

一次性生成所有规划产物，适用于你对要开发的功能已有清晰规划的场景。

实施（灵活环节）

/opsx:apply

逐条执行任务，完成后自动标记。若你同时处理多个变更，可执行 /opsx:apply <变更名称> 指定变更；否则系统会从对话中推断对应变更，无法识别时会提示你选择。

更新变更

/opsx:update add-dark-mode - we're storing the theme in a cookie now

修订变更的现有规划产物并保持内容一致性，修改方向不限（例如设计调整可能会反向影响提案）。该命令仅修改规划产物：不会编辑代码，也不会创建缺失的产物（创建产物请使用 /opsx:continue）。所有修改都会先征得你的确认。若变更已进入实施阶段，系统会推荐你执行 /opsx:apply，让代码与修订后的规划保持一致。如果你的修改会改变变更的核心目标，建议重新创建变更，详见何时更新 vs 重新创建。

完成归档

/opsx:archive   # 完成后归档（需要时会提示同步规格）

何时更新变更 vs 重新创建

实施前你随时可以修改提案或规格说明，但什么时候修改就变成了「完全不同的工作」？

提案涵盖的核心内容

提案会明确三个核心要素：

1. 目标——你要解决什么问题？
2. 范围——哪些内容在范围内，哪些在范围外？
3. 方案——你打算如何解决这个问题？

判断的关键是：哪些要素发生了变化，变化的程度有多大？

以下情况建议更新现有变更：

目标一致，仅优化执行方案

• 你发现了之前未考虑到的边界情况
• 方案需要微调，但核心目标不变
• 实施过程中发现设计存在细微偏差

范围缩小

• 你意识到完整范围过大，希望先发布最小可行版本（MVP）
• 「新增深色模式」→「新增深色模式切换开关（v2 版本支持系统偏好）」

基于实践反馈的修正

• 代码库结构与预想不符
• 某个依赖的表现不符合预期
• 「使用 CSS 变量」→「改用 Tailwind 的 dark: 前缀」

以下情况建议重新创建变更：

核心目标发生根本变化

• 要解决的问题本身已经改变
• 「新增深色模式」→「新增支持自定义颜色、字体、间距的完整主题系统」

范围大幅扩张

• 变更范围膨胀到本质上属于不同的工作
• 更新后的提案与原提案差异极大，无法识别
• 「修复登录漏洞」→「重写认证系统」

原变更可独立完成

• 原变更可以标记为「已完成」
• 新工作可独立开展，不属于原变更的优化
• 完成「新增深色模式 MVP」→归档→新建「优化深色模式」变更

判断准则

                        ┌─────────────────────────────────────┐
                        │     这是同一项工作吗？          │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             目标一致？        重叠度>50%？      不做这些修改，原变更
             问题相同？        范围一致？        能否标记为「完成」？
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
          是               否 是           否  否              是
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
        更新              新建 更新          新建 更新            新建

判断维度	更新现有变更	新建变更
身份一致性	「同一项工作，仅做优化」	「完全不同的工作」
范围重叠度	重叠度>50%	重叠度<50%
完成可行性	不做修改则无法标记原变更为「完成」	可完成原变更，新工作可独立开展
逻辑连贯性	更新链能形成连贯的修改记录	补丁式修改反而会让逻辑更混乱

核心原则

更新变更保留上下文，新建变更提供清晰度。

当你过往的思考过程仍有参考价值时，选择更新变更。 当你觉得重新开始比打补丁更清晰时，选择新建变更。

可以类比 Git 分支：

• 开发同一功能时持续提交 commit
• 当工作内容发生本质变化时，新建分支
• 有时可以先合并部分功能，再为第二阶段新建分支

有何不同？

	旧版工作流（/openspec:proposal）	OPSX（/opsx:*）
结构	单一的大型提案文档	带依赖关系的离散产物
工作流	线性阶段：规划→实施→归档	灵活动作——随时可执行任意操作
迭代效率	回溯修改十分繁琐	随认知深入随时更新产物
自定义能力	结构固定	架构驱动（可自行定义产物）

核心洞察：工作并非线性流程，OPSX 不再假装它是。

架构深度解析

本节将深入讲解OPSX的内部工作原理，并对比其与旧版工作流的差异。本节示例使用扩展命令集（new、continue等）；默认core用户可将相同流程映射为propose → apply → sync → archive。

设计理念：阶段 vs 动作

┌─────────────────────────────────────────────────────────────────────────────┐
│                         旧版工作流                                           │
│                    （阶段锁定，全有或全无）                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
│   │   规划阶段    │ ───► │   实施阶段    │ ───► │   归档阶段    │             │
│   └──────────────┘      └──────────────┘      └──────────────┘             │
│         │                     │                     │                       │
│         ▼                     ▼                     ▼                       │
│   /openspec:proposal   /openspec:apply      /openspec:archive              │
│                                                                             │
│   • 一次性创建所有产物                                                        │
│   • 实施过程中无法回头更新规范                                                  │
│   • 阶段关卡强制线性推进                                                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OPSX 工作流                                           │
│                      （灵活动作，迭代式）                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│              ┌────────────────────────────────────────────┐                 │
│              │           动作（而非阶段）                  │                 │
│              │                                            │                 │
│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
│              │    │          │           │           │    │                 │
│              │    └──────────┴───────────┴───────────┘    │                 │
│              │             任意顺序                        │                 │
│              └────────────────────────────────────────────┘                 │
│                                                                             │
│   • 可逐个创建产物，也可快速跳过所有步骤                                        │
│   • 实施过程中可更新规范/设计/任务                                             │
│   • 依赖关系用于推进进度，不存在阶段概念                                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

组件架构

旧版工作流使用硬编码的 TypeScript 模板：

┌─────────────────────────────────────────────────────────────────────────────┐
│                      旧版工作流组件                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   硬编码模板（TypeScript 字符串）                                             │
│                    │                                                        │
│                    ▼                                                        │
│   工具专属配置器/适配器                                                       │
│                    │                                                        │
│                    ▼                                                        │
│   生成的命令文件（.claude/commands/openspec/*.md）                            │
│                                                                             │
│   • 结构固定，无产物感知能力                                                  │
│   • 修改需改动代码并重新构建                                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

OPSX使用外部 Schema 和依赖图谱引擎：

┌─────────────────────────────────────────────────────────────────────────────┐
│                         OPSX 组件                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   Schema 定义（YAML）                                                        │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  name: spec-driven                                                  │   │
│   │  artifacts:                                                         │   │
│   │    - id: proposal                                                   │   │
│   │      generates: proposal.md                                         │   │
│   │      requires: []              ◄── 依赖关系                          │   │
│   │    - id: specs                                                      │   │
│   │      generates: specs/**/*.md  ◄── 通配符模式                        │   │
│   │      requires: [proposal]      ◄── 提案完成后解锁                    │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   产物图谱引擎                                                               │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │  • 拓扑排序（依赖顺序）                                              │   │
│   │  • 状态检测（文件系统存在性）                                        │   │
│   │  • 丰富指令生成（模板+上下文）                                        │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                    │                                                        │
│                    ▼                                                        │
│   技能文件（.claude/skills/openspec-*/SKILL.md）                              │
│                                                                             │
│   • 跨编辑器兼容（Claude Code、Cursor、Windsurf）                              │
│   • 技能查询 CLI 用于获取结构化数据                                            │
│   • 可通过 Schema 文件完全自定义                                               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

依赖图谱模型

产物构成有向无环图（DAG）。依赖关系是启用条件，而非关卡：

                              提案
                            （根节点）
                                 │
                   ┌─────────────┴─────────────┐
                   │                           │
                   ▼                           ▼
                规范                         设计
              （依赖：                      （依赖：
              提案）                        提案）
                   │                           │
                   └─────────────┬─────────────┘
                                 │
                                 ▼
                              任务
                           （依赖：
                           规范、设计）
                                 │
                                 ▼
                         ┌──────────────┐
                         │  应用阶段     │
                         │（依赖：       │
                         │ 任务）        │
                         └──────────────┘

状态流转：

   阻塞 ────────────────► 就绪 ────────────────► 完成
      │                        │                       │
   缺失依赖                 所有依赖均完成             文件存在于文件系统

信息流转

旧版工作流——代理接收静态指令：

  User: "/openspec:proposal"
           │
           ▼
  ┌─────────────────────────────────────────┐
  │  静态指令：                              │
  │  • 创建 proposal.md                      │
  │  • 创建 tasks.md                         │
  │  • 创建 design.md                        │
  │  • 创建 specs/<capability>/spec.md       │
  │                                          │
  │  不感知现有产物，也不感知产物间的依赖关系    │
  └─────────────────────────────────────────┘
           │
           ▼
  代理一次性创建所有产物

OPSX——代理查询富上下文：

  User: "/opsx:continue"
           │
           ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  步骤1：查询当前状态                                                      │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec status --change "add-auth" --json                      │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "artifacts": [                                                  │  │
  │  │      {"id": "proposal", "status": "done"},                         │  │
  │  │      {"id": "specs", "status": "ready"},      ◄── 首个就绪项        │  │
  │  │      {"id": "design", "status": "ready"},                          │  │
  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  步骤2：获取就绪产物的详细指令                                              │
  │  ┌────────────────────────────────────────────────────────────────────┐  │
  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
  │  │                                                                    │  │
  │  │  {                                                                 │  │
  │  │    "template": "# Specification\n\n## ADDED Requirements...",      │  │
  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
  │  │    "unlocks": ["tasks"]                                            │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  │                                                                          │
  │  步骤3：读取依赖项→创建单个产物→展示已解锁内容                                │
  └──────────────────────────────────────────────────────────────────────────┘

迭代模型

旧版工作流——迭代体验不佳：

  ┌─────────┐     ┌─────────┐     ┌─────────┐
  │/proposal│ ──► │ /apply  │ ──► │/archive │
  └─────────┘     └─────────┘     └─────────┘
       │               │
       │               ├── "等等，设计有问题"
       │               │
       │               ├── 可选操作：
       │               │   • 手动编辑文件（会丢失上下文）
       │               │   • 放弃并重新开始
       │               │   • 硬着头皮推进，后续再修复
       │               │
       │               └── 没有官方的“返回”机制
       │
       └── 一次性生成所有产物

OPSX — 自然迭代：

  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
      │                │                  │
      │                │                  ├── "设计有问题"
      │                │                  │
      │                │                  ▼
      │                │            直接编辑 design.md
      │                │            然后继续！
      │                │                  │
      │                │                  ▼
      │                │         /opsx:apply 会从
      │                │         你上次中断的地方继续
      │                │
      │                └── 一次生成一个产物，展示已解锁的内容
      │
      └── 搭建变更脚手架，等待下一步指示

自定义 Schema

使用 Schema 管理命令创建自定义工作流：

# 从零交互式创建新 Schema
openspec schema init my-workflow

# 或基于现有 Schema 分支创建自定义 Schema
openspec schema fork spec-driven my-workflow

# 验证 Schema 结构合法性
openspec schema validate my-workflow

# 查看 Schema 的解析来源（用于调试）
openspec schema which my-workflow

Schema 存储在 openspec/schemas/（项目本地，纳入版本控制）或 ~/.local/share/openspec/schemas/（用户全局）目录下。

Schema 结构：

openspec/schemas/research-first/
├── schema.yaml
└── templates/
    ├── research.md
    ├── proposal.md
    └── tasks.md

schema.yaml 示例：

name: research-first
artifacts:
  - id: research        # 在 proposal 之前生成
    generates: research.md
    requires: []

  - id: proposal
    generates: proposal.md
    requires: [research]  # 现在依赖 research 产物

  - id: tasks
    generates: tasks.md
    requires: [proposal]

依赖图：

   research ──► proposal ──► tasks

对比总结

维度	旧版本	OPSX
模板	硬编码 TypeScript	外部 YAML + Markdown
依赖关系	无依赖（一次性生成全部）	带拓扑排序的 DAG（有向无环图）
状态模型	基于阶段的思维模型	文件系统存在性
自定义能力	修改源码后重新构建	编写 schema.yaml
迭代方式	阶段锁定	灵活自由，可编辑任意内容
编辑器支持	工具专属的配置器/适配器	统一的 skills 目录

Schema

Schema 用于定义产物及其依赖关系。当前可用 Schema：

• spec-driven（默认）：proposal → specs → design → tasks

# 列出所有可用 Schema
openspec schemas

# 查看所有 Schema 及其解析来源
openspec schema which --all

# 交互式创建新 Schema
openspec schema init my-workflow

# 基于现有 Schema 分支创建自定义 Schema
openspec schema fork spec-driven my-workflow

# 使用前验证 Schema 结构
openspec schema validate my-workflow

使用技巧

• 在确定变更前，使用 /opsx:explore 梳理思路
• 明确目标时用 /opsx:ff，探索阶段用 /opsx:continue
• 执行 /opsx:apply 时如果发现问题，先修复对应产物再继续
• 任务进度通过 tasks.md 中的复选框追踪
• 随时可查看状态：openspec status --change "name"

反馈

这个功能还比较粗糙，这是有意为之——我们正在探索最优方案。

发现 bug？有改进建议？欢迎加入我们的 Discord 频道，或在 GitHub 提交 issue。