OPSX(openspec) 新用户实践 Cookbook本文详细介绍了 OPSX 这一 AI 驱动的流动式工作流，旨在

1. 快速开始

1.1 前置条件

确保你已经满足以下条件：

Node.js 20.19.0 或更高版本
已安装 OpenSpec CLI
AI 助手（推荐 Claude Code，也支持 20+ 其他工具）

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

# 在你的项目中初始化
cd your-project
openspec init

# 生成实验性技能
openspec experimental

1.2 理解核心概念

OPSX 是一个流动的、迭代的工作流，不同于传统的线性工作流：

传统工作流	OPSX 工作流
固定阶段	灵活行动
硬编码指令	可编辑模板
全有或全无	增量测试
黑盒操作	完全可控

核心思想：

行动 > 阶段 - 任何时间都可以创建、实施、更新、归档
依赖是使能器 - 它们显示可能性，而不是下一步的要求
迭代为王 - 边学边改，不需要等待完整的规划

1.3 项目结构

初始化后，你的项目将拥有以下结构：

openspec/
├── specs/              # 真源（系统的行为）
│   └── <domain>/
│       └── spec.md
├── changes/            # 拟议更新（每个变更一个文件夹）
│   └── <change-name>/
│       ├── .openspec.yaml  # 变更元数据
│       ├── proposal.md      # 提议
│       ├── design.md        # 设计（可选）
│       ├── tasks.md         # 任务列表
│       └── specs/           # 增量规格说明
│           └── <domain>/
│               └── spec.md
└── config.yaml         # 项目配置（可选）

2. 基础工作流

2.1 第一个变更：添加用户认证功能

让我们通过一个具体的例子来学习整个流程。

步骤 1：开始新变更

在 Claude Code 中输入：

/opsx:new add-user-auth

AI 会询问：

你想构建什么？
使用哪种工作流 schema？（默认 spec-driven）

你的回答：

我想添加用户认证功能，包括注册、登录和密码重置。
使用 spec-driven schema。

步骤 2：生成规划文档

有两个选择：

选项 A：一步生成所有规划文档

/opsx:ff

这会立即创建 proposal、specs、design 和 tasks。

选项 B：逐步创建

/opsx:continue

这会显示哪些 artifact 已准备就绪，并创建一个。

推荐： 新用户先使用 /opsx:ff 了解整体结构。

步骤 3：查看生成的文件

OPSX 会创建以下文件：

openspec/changes/add-user-auth/
├── proposal.md          # 为什么和什么
├── specs/               # 变更内容
│   ├── user-registration/
│   │   └── spec.md
│   ├── user-login/
│   │   └── spec.md
│   └── password-reset/
│       └── spec.md
├── design.md            # 如何实现
└── tasks.md             # 实施清单

步骤 4：审查和调整

查看 proposal.md：

# Why

我们的应用程序需要用户认证系统，以便：
- 保护敏感用户数据
- 跟踪用户活动
- 实现个性化功能

# What Changes

- **BREAKING**: 添加新的用户认证系统
- 新增用户注册端点
- 新增用户登录端点  
- 新增密码重置功能
- 集成 JWT token 验证中间件

# Capabilities

## New Capabilities
- `user-registration`: 用户注册功能
- `user-login`: 用户登录功能
- `password-reset`: 密码重置功能

## Modified Capabilities
- （无）

# Impact

- 后端 API 层：添加新的认证路由和中间件
- 数据库：需要 users 表和相关的索引
- 前端：需要登录页面和认证状态管理
- 现有 API：需要添加认证检查保护敏感端点

关键点：

Why：清晰的问题陈述
What Changes：具体的变更列表
Capabilities：定义了将要创建的规格说明
Impact：识别受影响的系统

步骤 5：实施任务

/opsx:apply

AI 会开始执行 tasks.md 中列出的任务，例如：

# Tasks

## 1. 数据库设计
- [ ] 设计 users 表结构
- [ ] 创建迁移脚本
- [ ] 添加必要的索引

## 2. 认证服务
- [ ] 实现密码哈希函数
- [ ] 实现用户注册逻辑
- [ ] 实现用户登录逻辑
- [ ] 实现 JWT token 生成和验证
- [ ] 实现密码重置流程

## 3. API 路由
- [ ] 创建 POST /auth/register
- [ ] 创建 POST /auth/login
- [ ] 创建 POST /auth/reset-password
- [ ] 创建 GET /auth/verify-token
- [ ] 添加认证中间件

## 4. 测试
- [ ] 编写单元测试
- [ ] 编写集成测试

步骤 6：完成和归档

当所有任务完成时：

/opsx:archive

这会：

将变更文件夹移动到 openspec/changes/archive/YYYY-MM-DD-add-user-auth/
将增量规格合并到主 openspec/specs/ 目录
清理工作区

3. 实践场景

场景 1：探索性开发

场景： 你有一个想法，但不完全确定解决方案。

/opsx:explore

示例对话：

你: /opsx:explore
AI: 我准备好帮你思考了。你想探索什么？

你: 我想知道如何为我们的 API 添加速率限制功能。
AI: 好的，让我们来探讨一下。
    
1. **固定窗口算法**：简单但可能不公平
   - 例如：每小时 100 次请求
   - 问题：用户可以在窗口开始时发送所有请求

2. **滑动窗口算法**：更平滑但需要更多内存
   - 基于时间戳追踪请求
   - 请求在固定期间内均匀分布

3. **令牌桶算法**：适合突发流量
   - 桶容量 × 令牌填充速率
   - 允许短时突发请求

4. **漏桶算法**：输出速率固定
   - 确保请求以恒定速率处理
   - 如果桶满则丢弃请求

根据你的用例，我建议使用令牌桶算法，因为：
- 能处理突发流量
- 广泛用于生产环境
- 有成熟的 Redis 实现

当你准备好时，运行 /opsx:new 来开始实现。

何时使用：

需要比较不同的技术方案
不清楚具体需求
想要快速验证想法

场景 2：增量实现

场景： 你有一个大的变更，但想分阶段实施。

# 第 1 阶段：基础认证
/opsx:new add-auth-mvp
/opsx:ff
/opsx:apply

# 归档第 1 阶段
/opsx:archive

# 第 2 阶段：2FA
/opsx:new add-two-factor-auth
/opsx:ff
/opsx:apply
/opsx:archive

优势：

更快的反馈循环
更容易回滚
可以基于第 1 阶段的经验调整第 2 阶段

场景 3：在实施过程中调整设计

场景： 你在实施过程中发现最初的设计有问题。

# 正在实施中...
/opsx:apply

# AI: "我发现数据库查询性能很差，建议添加缓存层。"

# 你可以停下来，更新设计
# 编辑 openspec/changes/add-user-auth/design.md
# 添加缓存策略

# 继续实施
/opsx:apply

关键点： OPSX 允许你随时更新任何 artifact。

场景 4：处理依赖关系

场景： 一个变更依赖于另一个变更。

# 第 1 个变更：添加用户模型
/opsx:new add-user-model
/opsx:ff
/opsx:apply

# 不归档，让其他变更可以依赖它

# 第 2 个变更：添加评论功能（需要用户模型）
/opsx:new add-comments
/opsx:ff
/opsx:apply

# 现在归档两个
/opsx:archive add-user-model
/opsx:archive add-comments

场景 5：自定义工作流 Schema

场景： 你的工作流与默认的 spec-driven 不同。

步骤 1：创建自定义 schema

# 创建项目级别的 schemas 目录
mkdir -p openspec/schemas/my-custom-workflow

# 创建 schema.yaml
cat > openspec/schemas/my-custom-workflow/schema.yaml << EOF
name: my-custom-workflow
version: 1
description: 我团队的自定义工作流
artifacts:
  - id: problem-statement
    generates: problem-statement.md
    description: 问题陈述
    template: problem-statement.md
    instruction: |
      清晰地定义问题。
      - 背景
      - 当前问题
      - 影响范围
    requires: []

  - id: solution-sketch
    generates: solution-sketch.md
    description: 解决方案草图
    template: solution-sketch.md
    instruction: |
      草拟解决方案。
      - 高级方法
      - 关键组件
      - 潜在风险
    requires:
      - problem-statement

  - id: spike
    generates: spike.md
    description: 技术调研
    template: spike.md
    instruction: |
      进行技术调研。
      - 验证假设
      - 确定可行性
      - 估算工作量
    requires:
      - solution-sketch

  - id: implementation-plan
    generates: implementation-plan.md
    description: 实施计划
    template: implementation-plan.md
    instruction: |
      制定实施计划。
      - 详细步骤
      - 里程碑
      - 验收标准
    requires:
      - spike
EOF

# 创建模板
# 创建 openspec/schemas/my-custom-workflow/templates/ 目录
# 并添加相应的 .md 模板文件

步骤 2：使用自定义 schema

/opsx:new my-feature --schema my-custom-workflow

4. 进阶技巧

4.1 项目配置

创建 openspec/config.yaml 来自定义默认行为：

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API conventions: RESTful, JSON responses
  Testing: Vitest for unit tests, Playwright for e2e
  Style: ESLint with Prettier, strict TypeScript
  Database: Prisma ORM
  Deployment: Vercel for frontend, Railway for backend

rules:
  proposal:
    - 必须包含回滚计划
    - 识别受影响的团队
  specs:
    - 使用 Given/When/Then 格式编写场景
    - 每个需求至少有一个场景
  design:
    - 对复杂流程包含序列图
  tasks:
    - 每个任务必须可估算
    - 包含验收标准

优势：

上下文会自动注入到所有 artifact 的指令中
规则确保团队的一致性
不需要重复设置

4.2 多个变更同时进行

# 变更 1
/opsx:new add-dark-mode
/opsx:ff

# 变更 2（不完成变更 1）
/opsx:new optimize-images
/opsx:ff

# 实施特定变更
/opsx:apply add-dark-mode

# 切换到另一个
/opsx:apply optimize-images

4.3 版本控制和协作

推荐的分支策略：

main
├── feature/add-user-auth
│   └── openspec/changes/add-user-auth/
└── feature/add-comments
    └── openspec/changes/add-comments/

协作最佳实践：

每个功能一个变更文件夹
- 避免将多个功能混在一起
- 便于代码审查和回滚
在 PR 中包含 spec
- 提议、规格和设计作为 PR 描述
- 帮助审查者理解意图
更新规格时审查 PR
- 增量规格应该像代码一样审查
- 确保需求清晰且可测试

4.4 使用 Delta Specs

理解 Delta Specs 的格式：

# Delta for User Registration

# ADDED Requirements

## Requirement: 用户必须提供有效的电子邮件地址
系统 MUST 验证电子邮件地址格式并确保其唯一性。

### Scenario: 成功注册
- **GIVEN** 访问注册页面
- **WHEN** 用户输入有效的电子邮件地址和密码
- **THEN** 创建用户账户并发送验证邮件

### Scenario: 无效的电子邮件格式
- **GIVEN** 访问注册页面
- **WHEN** 用户输入无效的电子邮件格式
- **THEN** 显示"无效的电子邮件地址"错误

# MODIFIED Requirements

## Requirement: 密码复杂度
系统 MUST 要求密码至少 8 个字符，包含大小写字母和数字。

### Scenario: 弱密码
- **GIVEN** 访问注册页面
- **WHEN** 用户输入弱密码（例如 "password"）
- **THEN** 显示"密码必须至少 8 个字符，包含大小写字母和数字"错误

# REMOVED Requirements

## Requirement: 密码中必须包含特殊字符
**Reason**: 太严格，影响用户体验
**Migration**: N/A（未实现）

关键规则：

每个 requirement 使用 3 个井号 (###)
每个 scenario 使用 4 个井号 (####)
MODIFIED requirements 必须包含完整内容（而不是差异）
REMOVED requirements 必须包含原因和迁移计划

4.5 测试驱动开发（TDD）与 OPSX

OPSX 与 TDD 非常契合：

# 1. 创建规格（每个场景都是一个潜在的测试用例）
/opsx:new feature-x
/opsx:continue  # 创建 proposal
/opsx:continue  # 创建 specs

# 2. 基于 scenarios 编写测试
# scenarios 会明确地说明期望的行为

# 3. 实施功能
/opsx:apply

# 4. 验证测试通过
# 运行测试套件

5. 常见问题

Q1: 什么时候更新现有变更 vs. 创建新变更？

使用现有变更，当：

相同的意图
50% 范围重叠
在这些更改下无法"完成"原变更

创建新变更，当：

意图根本改变
<50% 范围重叠
原变更可以单独完成

决策树：

这是相同的工作吗？
   │
   ├── 相同的意图？
   │    │
   │    ├── 是 → 更新
   │    └── 否 → 新变更
   │
   ├── >50% 重叠？
   │    │
   │    ├── 是 → 更新
   │    └── 否 → 新变更
   │
   └── 原变更可单独完成？
        │
        ├── 否 → 更新
        └── 是 → 新变更

Q2: `/opsx:ff` 和 `/opsx:continue` 有什么区别？

命令	用途	何时使用
`/opsx:ff`	一次性生成所有规划文档	你对要构建的内容有清晰的认识
`/opsx:continue`	逐步创建 artifact	你想在每个 artifact 后审查和调整

示例：

# 快速路径：你已经知道要做什么
/opsx:new add-dark-mode
/opsx:ff
/opsx:apply

# 保守路径：你想在每个步骤思考
/opsx:new add-dark-mode
/opsx:continue  # 创建 proposal，审查它
/opsx:continue  # 创建 specs，审查它们
/opsx:continue  # 创建 design，审查它
/opsx:continue  # 创建 tasks，审查它们
/opsx:apply

Q3: 如何回滚变更？

在归档之前：

# 只需删除变更文件夹
rm -rf openspec/changes/your-change/

在归档之后：

# 从归档恢复
cp -r openspec/changes/archive/YYYY-MM-DD-your-change/ openspec/changes/your-change/

# 恢复规格（需要手动）
# 从归档的变更中查看增量规格
# 相应地更新主规格文件

更好的方法： 使用 Git！

# 归档创建了提交
# 要回滚，只需恢复到之前的提交
git revert <commit-hash>

Q4: AI 生成的代码质量很差，该怎么办？

调整模板：

编辑模板文件

# 编辑提案模板
vi openspec/schemas/spec-driven/templates/proposal.md

# 编辑设计模板
vi openspec/schemas/spec-driven/templates/design.md

添加更具体的指令

## Design Guidelines

- 使用 TypeScript 严格模式
- 遵循 SOLID 原则
- 错误处理必须明确
- 添加 JSDoc 注释

在项目配置中添加规则

# openspec/config.yaml
rules:
  design:
    - 包含序列图表示复杂流程
    - 确定所有外部依赖
    - 包含性能考虑

重新生成

# 删除现有 artifact
rm openspec/changes/your-change/design.md

# 重新创建
/opsx:continue

Q5: 如何处理跨多个服务的变更？

使用 design.md：

# 涉及的服务

- 用户服务：处理用户认证
- 订单服务：创建和管理订单
- 支付服务：处理交易
- 通知服务：发送邮件和推送通知

# 服务间的交互

用户服务 → 订单服务 → 支付服务 ↓ 通知服务


# 数据一致性

- 使用 saga 模式确保分布式事务
- 每个服务维护自己的数据存储
- 通过事件总线进行通信

# API 契约

定义所有服务间的 API 端点和消息格式。

Q6: 如何集成到 CI/CD？

验证规格：

# .github/workflows/validate-specs.yml
name: Validate Specs

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install OpenSpec
        run: npm install -g @fission-ai/openspec@latest
      
      - name: Validate all changes
        run: |
          for dir in openspec/changes/*/; do
            echo "Validating $dir"
            openspec validate "$dir"
          done

运行测试：

# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Generate test coverage
        run: npm run coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3

Q7: 如何追踪进度？

使用 tasks.md 的复选框：

# Tasks

## Phase 1: 数据库
- [x] 设计数据库 schema
- [x] 创建迁移脚本
- [ ] 迁移生产数据

## Phase 2: 后端
- [ ] 实现 API 端点
- [ ] 添加认证
- [ ] 编写单元测试

## Phase 3: 前端
- [ ] 创建 UI 组件
- [ ] 集成 API
- [ ] 端到端测试

在实施期间检查：

/opsx:show my-change

这会显示当前状态和剩余任务。

Q8: 如何处理紧急修复？

快速路径：

# 开始变更
/opsx:hotfix fix-critical-bug --schema simple

# 立即实施
/opsx:apply

# 快速归档
/opsx:archive

或者创建一个 simple schema，只包含：

name: simple
version: 1
artifacts:
  - id: fix-description
    generates: fix-description.md
    description: 简要描述修复
    template: fix-description.md
    instruction: |
      描述问题、根本原因和解决方案。
    requires: []

总结

OPSX 的核心价值：

灵活性 - 做任何你需要的，随时
透明度 - 你能看到并控制一切
迭代性 - 边学边改
可定制性 - 适应你的工作流

记住：

从小开始，然后扩展
更改是可预期的，不是意外
规格是契约，而不仅仅是文档
工作流是工具，而非枷锁

下一步：

查看这些资源以了解更多：

项目配置指南 - 深入了解 config.yaml
自定义工作流 schemas - 创建你自己的工作流
验证规则 - 确保规格质量
团队协作 - 多人使用 OPSX

附录：快速参考

OPSX 斜杠命令

命令	功能	示例
`/opsx:explore`	探索想法	`/opsx:explore`
`/opsx:new`	开始新变更	`/opsx:new add-feature`
`/opsx:continue`	创建下一个 artifact	`/opsx:continue`
`/opsx:ff`	快速生成所有规划	`/opsx:ff`
`/opsx:apply`	实施任务	`/opsx:apply`
`/opsx:archive`	归档完成的变更	`/opsx:archive`

Artifact 依赖关系

proposal (无依赖)
  ↓
specs (依赖 proposal)
  ↓
design (依赖 specs)
  ↓
tasks (依赖 design)
  ↓
implementation (依赖 tasks)

文件位置

文件	位置
项目配置	`openspec/config.yaml`
项目 schemas	`openspec/schemas/`
变更	`openspec/changes/<name>/`
主规格	`openspec/specs/`
归档的变更	`openspec/changes/archive/`

祝你在 OPSX 的旅程愉快！记住：完美的实践是通过迭代来实现的，而不是通过一次性完美地完成所有事情。 🚀

OPSX(openspec) 新用户实践 Cookbook

目录