名称： openspec
描述： 使用 OpenSpec CLI 进行规范驱动开发。适用于功能开发、迁移、重构或任何结构化开发工作。管理从提案 → 规范 → 设计 → 任务 → 实现的完整工作流。支持自定义模式（如 TDD、快速开发等）。当涉及功能规划、规范编写、变更管理或提及 /opsx 命令时触发使用。

OpenSpec — 规范驱动开发

OpenSpec 将 AI 辅助的开发过程结构化，形成可追踪的变更，并通过提案、规范、设计、任务等工件来指导实现。

安装与初始化

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

# 在项目中初始化
cd /path/to/project
openspec init --tools claude

# CLI 升级后更新
openspec update

核心工作流

每次变更遵循：新建 → 规划 → 应用 → 验证 → 归档

1. 启动变更

# 使用默认模式创建变更文件夹
openspec new change <变更名称>

# 使用特定模式
openspec new change <变更名称> --schema tdd-driven

2. 规划（创建工件）

使用 CLI 的 instructions 命令获取每个工件的详细创建提示：

# 获取下一个工件的创建说明
openspec instructions --change <变更名称> --json

# 检查进度
openspec status --change <变更名称> --json

工件序列（规范驱动模式）：
1. proposal.md — 说明原因与内容（意图、范围、方法）
2. specs/ — 需求与场景（Given/When/Then）
3. design.md — 技术方案与架构决策
4. tasks.md — 带复选框的实现清单

3. 实现

阅读 tasks.md 并逐项完成，标记 [x] 表示完成。

4. 验证

openspec validate --change <变更名称> --json

检查完整性、正确性和一致性。

5. 归档

openspec archive <变更名称> --yes

将增量规范合并到主 openspec/specs/ 目录，并将变更移至归档。

AI 代理工作流（作为 AI 代理的使用方法）

当用户要求使用 OpenSpec 构建/迁移/重构时：

1. 检查项目状态：
   bash openspec list --json # 活动中的变更 openspec list --specs --json # 当前规范 openspec schemas --json # 可用模式

2. 创建变更：
   bash openspec new change <变更名称> [--schema <模式名称>]

3. 为每个工件获取说明并创建文件：
   bash openspec instructions <工件名> --change <变更名称> --json openspec status --change <变更名称> --json
   然后将工件文件写入 openspec/changes/<变更名称>/。

4. 根据 tasks.md 实现任务。

5. 验证并归档：
   bash openspec validate <变更名称> --json openspec archive <变更名称> --yes

CLI 快速参考

程序化或代理使用时请始终添加 --json 选项。

自定义模式

模式定义了工件的序列。可为不同工作流创建自定义模式：

# 基于内置模式创建分支
openspec schema fork spec-driven my-workflow

# 从头创建
openspec schema init my-workflow

# 验证
openspec schema validate my-workflow

模式文件位于 openspec/schemas/<模式名称>/schema.yaml，模板位于 templates/ 目录。

有关模式结构的详细信息，请参阅 references/schemas.md。

项目结构

项目目录/
├── openspec/
│   ├── config.yaml          # 项目配置（默认模式、上下文、规则）
│   ├── specs/               # 单一事实来源 — 当前系统行为规范
│   ├── changes/             # 活动中的变更（每个变更一个文件夹）
│   │   └── <变更名称>/
│   │       ├── .openspec.yaml
│   │       ├── proposal.md
│   │       ├── specs/       # 增量规范（描述变更内容）
│   │       ├── design.md
│   │       └── tasks.md
│   └── schemas/             # 自定义模式
└── .claude/skills/          # 自动生成的 Claude 集成

规范格式

规范使用 RFC 2119 关键词（SHALL/MUST/SHOULD/MAY）和 Given/When/Then 场景：

### 需求：用户认证
系统 SHALL 在成功登录后颁发 JWT 令牌。

#### 场景：有效凭据
- GIVEN 一个拥有有效凭据的用户
- WHEN 用户提交登录表单
- THEN 返回一个 JWT 令牌

增量规范

变更不会重写规范 — 它们描述的是增量（ADDED/MODIFIED/REMOVED），归档时会合并到主规范中。

配置

openspec/config.yaml 设置默认值：

schema: spec-driven      # 或 tdd-driven, rapid, custom
context: |
  技术栈：TypeScript, React, Node.js
  测试：Jest
rules:
  proposal:
    - 包含回滚计划
  specs:
    - 使用 Given/When/Then 格式