OpenSpec 操作手册

OpenSpec 是一个规范驱动的开发工作流系统，帮助您系统化地思考、规划和实施代码变更。

📚 目录

  1. 核心概念
  2. 工作流程
  3. 命令详解
  4. 实战示例
  5. 最佳实践
  6. 常见问题

🎯 核心概念

什么是 OpenSpec？

OpenSpec 是一个帮助您在编写代码之前进行思考和规划的系统。它通过结构化的工件（artifacts）来捕获您的思考过程：

  • 为什么做这个变更（Proposal）
  • 做什么具体需求（Specs）
  • 怎么做技术设计（Design）
  • 做哪些任务清单（Tasks）

变更（Change）

变更是 OpenSpec 的基本单位，代表一个完整的工作项。每个变更都存储在独立的目录中：

openspec/changes/<变更名>/
├── proposal.md      # 提案：为什么要做这个变更
├── specs/           # 规范：详细的需求定义
│   └── <能力名>/
│       └── spec.md
├── design.md        # 设计：技术方案和决策
└── tasks.md         # 任务：实施清单

工件（Artifacts）

工件是变更中的各个组成部分：

工件用途何时创建
Proposal回答"为什么"，定义变更的价值和范围第一步
Specs回答"做什么"，用可测试的方式定义需求提案之后
Design回答"怎么做"，记录技术决策和方案规范之后
Tasks回答"做哪些"，将工作分解为可执行步骤设计之后

工作流模式（Schema）

OpenSpec 支持不同的工作流模式，当前项目使用 spec-driven（规范驱动）模式：

Proposal → Specs → Design → Tasks → Implementation

🔄 工作流程

完整的变更生命周期

┌──────────┐
│  探索    │  思考问题，不写代码
│ Explore  │  /opsx:explore
└────┬─────┘
     │
     ▼
┌──────────┐
│  创建    │  创建变更容器
│  New     │  /opsx:new <名称> 或 /opsx:ff <名称>
└────┬─────┘
     │
     ▼
┌──────────┐
│  构建    │  逐步创建工件
│ Artifacts│  Proposal → Specs → Design → Tasks
└────┬─────┘
     │
     ▼
┌──────────┐
│  实施    │  执行任务清单
│  Apply   │  /opsx:apply <名称>
└────┬─────┘
     │
     ▼
┌──────────┐
│  验证    │  确认符合规范
│  Verify  │  /opsx:verify <名称>
└────┬─────┘
     │
     ▼
┌──────────┐
│  归档    │  完成后归档
│ Archive  │  /opsx:archive <名称>
└──────────┘

两种创建方式

1. 逐步模式（/opsx:new）

适合：复杂变更、需要深入思考的功能

/opsx:new add-user-export

→ 创建变更目录
→ 引导您逐个创建工件
→ 每步都有模板和提示
→ 可以随时暂停和继续
2. 快速模式（/opsx:ff）

适合：简单变更、思路清晰的功能

/opsx:ff fix-login-timeout

→ 一次性生成所有工件
→ 基于您的描述自动填充
→ 可以后续手动调整
→ 快速进入实施阶段

📖 命令详解

🔍 探索模式

/opsx:explore

**用途：**思考伙伴，帮助您探索想法、调查问题、澄清需求

特点：

  • ✅ 可以读文件、搜索代码、调查代码库
  • ✅ 可以创建 OpenSpec 工件（捕获思考）
  • ❌ 不会写代码或实施功能
  • ✅ 自由对话，没有固定步骤

何时使用：

  • 不确定如何实现某个功能
  • 需要比较多个技术方案
  • 想要理解现有代码架构
  • 发现问题但不清楚根本原因

示例对话：

您：/opsx:explore
您：我想优化批量导入的性能，但不确定瓶颈在哪里

Claude：让我先分析一下现有的导入流程...
[读取相关代码文件]
[绘制流程图]
[识别性能瓶颈]
[提出优化方案]

可视化：
探索模式会大量使用 ASCII 图表帮助您理解：

当前导入流程
═══════════════════════════════════════

  ┌─────────┐
  │  读取   │  ← 瓶颈1: 逐行读取
  │  文件   │
  └────┬────┘
       │
       ▼
  ┌─────────┐
  │  验证   │  ← 瓶颈2: 重复查询数据库
  │  数据   │
  └────┬────┘
       │
       ▼
  ┌─────────┐
  │  插入   │  ← 瓶颈3: 单条插入
  │  数据库 │
  └─────────┘

🆕 创建新变更

逐步模式
/opsx:new <变更名>

参数：

  • <变更名>：kebab-case 格式（如 add-export-feature）
  • 可选：--schema <模式名> 使用非默认工作流

流程：

  1. 创建变更目录

    openspec/changes/add-export-feature/

  2. 显示第一个工件的模板

    当前状态: 0/4 工件完成
下一步: 创建 proposal.md

模板已显示，请描述您的变更...

  3. 逐个引导创建工件

    • Proposal → Specs → Design → Tasks
    • 每步都有清晰的指导
    • 可以随时用 /opsx:continue 继续

示例：

您：/opsx:new add-batch-delete
Claude：已创建变更 add-batch-delete
        让我们从提案开始，请描述：
        - 为什么需要批量删除功能？
        - 这会影响哪些用户？

您：管理员需要一次性删除多条记录，当前只能逐条删除效率太低

Claude：[生成 proposal.md 草稿]
        [等待您确认]
        [保存后继续到 specs]
快速模式
/opsx:ff <变更名>

特点：

  • 一次性生成所有工件
  • 基于您的一段描述
  • 适合思路清晰的变更

示例：

您：/opsx:ff optimize-import-speed

    我想优化批量导入功能的性能。当前导入1000条记录需要30秒，
    希望优化到5秒以内。主要问题是逐行处理和单条插入数据库。

Claude：[分析需求]
        [生成完整的 proposal、specs、design、tasks]
        [显示生成的工件]

        所有工件已创建！准备好开始实施了吗？

🔄 继续现有变更

/opsx:continue <变更名>

**用途：**继续之前暂停的变更工作

场景：

  • 创建工件时中断了
  • 需要补充或修改已有工件
  • 查看变更当前状态

示例：

您：/opsx:continue add-batch-delete

Claude：变更 add-batch-delete 当前状态：
        ✓ proposal.md 已完成
        ✓ specs/batch-delete/ 已完成
        ⚠ design.md 进行中
        ○ tasks.md 待创建

        继续完成 design.md？

⚡ 实施任务

/opsx:apply <变更名>

**用途：**执行 tasks.md 中的任务清单，实施代码变更

流程：

  1. 读取任务清单

    读取 openspec/changes/<名称>/tasks.md
解析所有待完成任务

  2. 逐个执行任务

    [ ] 1.1 添加批量删除 API 端点
↓
正在执行: 1.1 添加批量删除 API 端点
↓
[x] 1.1 添加批量删除 API 端点 ✓

  3. 参考规范和设计

    • 确保实现符合 specs 的要求
    • 遵循 design 中的技术决策
    • 自然地提及对应关系

示例输出：

开始实施 add-batch-delete...

✓ 任务 1.1: 添加 BatchDeleteController
  按照设计文档使用 JAX-RS 注解实现

✓ 任务 1.2: 实现批量删除服务
  规范要求: 支持最多100条记录批量操作

✓ 任务 2.1: 添加前端批量选择功能

✓ 任务 3.1: 编写单元测试

所有任务完成！建议运行 /opsx:verify 验证实现。

✅ 验证实施

/opsx:verify <变更名>

**用途：**验证实施是否符合规范和设计

检查项：

  • ✓ Specs 中的所有需求是否已实现
  • ✓ Design 中的技术决策是否被遵循
  • ✓ Tasks 中的任务是否全部完成
  • ✓ 代码是否引入了新的问题

示例：

您：/opsx:verify add-batch-delete

Claude：验证 add-batch-delete...

        ✓ Proposal 目标达成
        ✓ 所有规范场景已实现
        ✓ 设计决策已遵循
        ✓ 所有任务已完成

        ⚠ 发现 1 个问题:
        - 批量删除 API 缺少权限检查
          (规范 2.3 要求: 只有管理员可以批量删除)

        建议修复后再归档。

📦 归档变更

/opsx:archive <变更名>

**用途：**将完成的变更移到归档目录

效果：

openspec/changes/add-batch-delete/
↓ 移动到
openspec/changes/archive/2026-02-11-add-batch-delete/

价值：

  • 保留决策历史
  • 方便未来回顾"为什么这样做"
  • 清理活跃变更目录

示例：

您：/opsx:archive add-batch-delete

Claude：已归档到: openspec/changes/archive/2026-02-11-add-batch-delete/

        变更记录已保存，代码已在代码库中。
        未来可以查看这个目录了解为什么添加批量删除功能。

📚 其他命令

批量归档
/opsx:bulk-archive

一次归档多个已完成的变更。

同步规范
/opsx:sync-specs

将变更中的规范同步到主规范库 openspec/specs/。

新手引导
/opsx:onboard

完整的交互式教程，通过实际的代码变更学习 OpenSpec 工作流。

推荐给初次使用者！

🎮 实战示例

示例 1：添加新功能（逐步模式）

**场景：**为项目管理系统添加数据导出功能

# 第 1 步：进入探索模式思考
/opsx:explore

您：我想添加数据导出功能，用户可以导出项目数据为 Excel

Claude：让我们先理清需求...

        导出功能的范围
        ═══════════════════════════════════

        1. 导出什么数据？
           □ 项目基本信息
           □ 关联的管道数据
           □ 设计文档
           □ 检验记录

        2. 谁可以导出？
           □ 所有用户
           □ 项目成员
           □ 仅管理员

        3. 导出格式？
           □ Excel (.xlsx)
           □ CSV
           □ PDF

        请告诉我更多细节...

您：导出项目基本信息和管道数据，项目成员可以导出，格式为 Excel

Claude：明白了。让我画个流程图：

        导出流程
        ══════════════════════════════════

        ┌─────────────┐
        │ 用户点击    │
        │ 导出按钮    │
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │ 权限检查    │  ← 必须是项目成员
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │ 查询数据    │  ← 项目信息 + 管道数据
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │ 生成 Excel  │  ← 使用 Apache POI
        └──────┬──────┘
               │
               ▼
        ┌─────────────┐
        │ 下载文件    │
        └─────────────┘

        技术方案：
        - 后端：使用 Apache POI 生成 Excel
        - 前端：调用下载 API
        - 权限：检查用户是否在项目成员表中

        准备好创建变更了吗？

# 第 2 步：创建变更
/opsx:new add-project-export

Claude：已创建变更 add-project-export

        让我们从提案开始。基于我们的探索，我起草了一份提案：

        ---
        ## 为什么

        项目成员需要导出项目数据进行离线分析和汇报。当前系统不支持
        数据导出，用户只能手动复制数据，效率低且容易出错。

        ## 做什么

        添加数据导出功能，允许项目成员将项目基本信息和关联的管道数据
        导出为 Excel 文件。

        ## 能力

        ### 新增能力
        - `project-data-export`: 将项目数据导出为 Excel 格式

        ## 影响

        - 后端：新增 `ExportController` 和 `ExportService`
        - 前端：项目详情页面添加导出按钮
        - 依赖：引入 Apache POI 库
        ---

        这个提案可以吗？

您：可以

Claude：已保存 proposal.md

        接下来创建规范。我会定义导出功能的详细需求...

        [继续创建 specs、design、tasks]

# 第 3 步：实施任务
/opsx:apply add-project-export

Claude：开始实施 add-project-export...

        ✓ 任务 1.1: 添加 Apache POI 依赖到 pom.xml
        ✓ 任务 1.2: 创建 ExportController 类
          按照规范: @Path("/api/export")
        ✓ 任务 1.3: 实现 ExportService.exportProjectData()
          按照设计: 使用 POI 的 XSSFWorkbook
        ✓ 任务 2.1: 添加前端导出按钮
        ✓ 任务 2.2: 实现 API 调用和文件下载
        ✓ 任务 3.1: 编写单元测试

        所有任务完成！

# 第 4 步：验证和归档
/opsx:verify add-project-export
/opsx:archive add-project-export

示例 2：修复性能问题（快速模式）

**场景：**批量导入功能性能差，需要优化

/opsx:ff optimize-batch-import

当前批量导入1000条记录需要30秒，主要问题：
1. 逐行读取Excel文件
2. 每条记录单独进行数据库查询验证
3. 使用单条INSERT而非批量插入

优化方案：
1. 使用POI的流式读取(SXSSF)减少内存占用
2. 预加载验证数据到内存Map中
3. 使用JDBC批量插入，每批500条

目标：将导入时间降低到5秒以内

Claude：分析您的需求...

        [生成完整的 proposal.md]
        [生成 specs/batch-import-optimization/spec.md]
        [生成 design.md，包含性能对比]
        [生成 tasks.md，分解为具体优化步骤]

        所有工件已创建！这是任务清单：

        ## 1. 优化文件读取
        - [ ] 1.1 替换 XSSF 为 SXSSF 流式读取
        - [ ] 1.2 添加内存监控日志

        ## 2. 优化数据验证
        - [ ] 2.1 预加载验证数据到 HashMap
        - [ ] 2.2 重构验证逻辑避免重复查询

        ## 3. 优化数据库插入
        - [ ] 3.1 实现批量插入，批大小500
        - [ ] 3.2 添加事务控制

        ## 4. 性能测试
        - [ ] 4.1 测试1000条记录导入时间
        - [ ] 4.2 测试5000条记录导入时间

        准备好实施了吗？

/opsx:apply optimize-batch-import

示例 3：重构代码

**场景：**现有的文档管理代码混乱，需要重构

/opsx:explore

您：doc包下的代码很乱，controller、service、utils混在一起，能帮我理清楚吗？

Claude：让我先看看当前结构...

        [读取 doc/ 目录]
        [分析文件依赖关系]

        当前文档管理模块结构
        ═══════════════════════════════════════

        doc/
        ├── DocController.java       ← REST端点
        ├── DocService.java          ← 业务逻辑
        ├── DocUploadUtil.java       ← 上传工具
        ├── DocDownloadUtil.java     ← 下载工具
        ├── DocValidator.java        ← 验证逻辑
        ├── DocDTO.java              ← 数据传输对象
        └── DocRepository.java       ← 数据访问


        问题分析
        ════════════════════════════════════════

        1. 缺少清晰的分层
           Controller/Service/Utils 在同一层级

        2. 工具类和业务类混在一起
           DocUploadUtil 和 DocService 边界不清

        3. 缺少子包组织
           所有类都在 doc/ 根目录


        建议的目标结构
        ════════════════════════════════════════

        doc/
        ├── controller/
        │   └── DocController.java
        ├── service/
        │   ├── DocService.java
        │   └── DocValidationService.java
        ├── repository/
        │   └── DocRepository.java
        ├── dto/
        │   ├── DocDTO.java
        │   └── DocUploadDTO.java
        └── util/
            ├── DocUploadUtil.java
            └── DocDownloadUtil.java


        这样重构后：
        ✓ 清晰的分层结构
        ✓ 职责明确
        ✓ 易于维护和扩展

        要不要创建一个重构变更？

/opsx:ff refactor-doc-structure

重构doc包的目录结构，将代码按照controller/service/repository/dto/util
进行分层组织，提升代码可维护性。这是一个纯重构，不改变功能行为。

💡 最佳实践

1. 命名规范

变更名称使用 kebab-case：

✓ add-user-export
✓ fix-login-timeout
✓ optimize-batch-import
✓ refactor-doc-structure

✗ addUserExport
✗ Fix_Login_Timeout
✗ OPTIMIZE_BATCH_IMPORT

能力名称使用 kebab-case：

✓ user-data-export
✓ batch-import-optimization
✓ document-structure-refactoring

✗ userDataExport
✗ BatchImportOptimization

2. 何时使用探索模式

适合探索的场景：

  • ❓ 需求不清晰，需要理清思路
  • 🤔 有多个技术方案，不确定选哪个
  • 🔍 需要调查现有代码架构
  • 🐛 发现Bug但不清楚根本原因
  • 📊 需要性能分析找出瓶颈

示例：

# 先探索
/opsx:explore
# 讨论清楚后创建变更
/opsx:new <名称>

3. 选择逐步模式还是快速模式

场景推荐模式原因
大型新功能/opsx:new需要深入思考每个环节
复杂重构/opsx:new需要详细记录决策过程
架构调整/opsx:new涉及多个模块，需要仔细规划
简单修复/opsx:ff思路清晰，快速完成
小优化/opsx:ff范围明确，不需要过多讨论
添加工具方法/opsx:ff实现直接，一次性生成即可

4. 编写高质量的提案

好的提案应该回答：

  1. 为什么要做这个变更？

    • 解决什么问题？
    • 带来什么价值？
    • 不做会怎样？

  2. 做什么（高层次）？

    • 会改变什么？
    • 新增什么能力？
    • 影响哪些模块？

  3. 不做什么（非目标）？

    • 明确边界
    • 避免范围蔓延

示例对比：

❌ 不好的提案：

## 为什么
需要添加导出功能

## 做什么
添加一个导出按钮

✅ 好的提案：

## 为什么

项目成员经常需要将项目数据导出用于离线分析和向领导汇报。
当前系统不支持导出，用户只能手动复制粘贴数据到Excel，
这个过程耗时且容易出错，特别是在需要导出大量数据时。

## 做什么

添加项目数据导出功能，允许项目成员一键导出项目的基本信息
和关联的管道数据为Excel文件。导出内容包括项目名称、状态、
负责人、创建时间、管道列表及其详细参数。

## 新增能力

- `project-data-export`: 将指定项目的数据导出为Excel格式

## 非目标

- 不包含文档和图纸的导出（由文档管理模块负责）
- 不支持自定义导出字段（后续版本考虑）
- 不支持定时自动导出（如有需求单独规划）

## 影响

- 后端: 新增 ExportController 和 ExportService
- 前端: 项目详情页添加"导出"按钮
- 依赖: 引入 Apache POI 库（已用于其他导出功能）

5. 编写可测试的规范

使用 WHEN/THEN/AND 格式：

## 需求：批量删除项目数据

### 场景：成功删除多条记录

- **WHEN** 管理员选择3条记录并点击批量删除
- **THEN** 系统删除这3条记录
- **AND** 显示"成功删除3条记录"的提示
- **AND** 列表自动刷新不再显示已删除记录

### 场景：权限不足

- **WHEN** 普通用户尝试批量删除
- **THEN** 系统拒绝操作
- **AND** 显示"权限不足"的错误提示

### 场景：部分失败

- **WHEN** 批量删除5条记录，其中2条正在被其他流程使用
- **THEN** 系统删除3条未被使用的记录
- **AND** 保留2条被使用的记录
- **AND** 显示"成功删除3条，2条因被使用而跳过"

6. 记录设计决策的理由

不仅说"怎么做"，更要说"为什么这样做"：

## 决策：使用流式读取Excel

### 方案选择

考虑了三种方案：

| 方案 | 优点 | 缺点 | 是否采用 |
|------|------|------|----------|
| 全量加载到内存 | 实现简单 | 大文件会OOM | ❌ |
| 流式读取(SXSSF) | 内存可控 | 代码稍复杂 | ✅ |
| 分块处理 | 内存可控 | 性能不如流式 | ❌ |

### 选择理由

选择流式读取（SXSSF）的原因：

1. **内存安全**：用户可能上传10MB+的大文件，全量加载会导致OOM
2. **性能良好**：SXSSF专为大文件设计，性能接近原生读取
3. **生态成熟**：Apache POI官方推荐方案，文档和案例丰富
4. **代码可控**：复杂度增加有限，团队已有类似经验

### 实现要点

- 使用 `SXSSFWorkbook` 替代 `XSSFWorkbook`
- 设置滑动窗口大小为100行（`new SXSSFWorkbook(100)`）
- 及时调用 `row.dispose()` 释放已处理行

7. 任务分解原则

好的任务应该：

  1. 粒度适中：2-4小时完成
  2. 职责单一：只做一件事
  3. 可验证：完成后能明确检查
  4. 有顺序：考虑依赖关系

示例：

## 1. 后端实现

- [ ] 1.1 添加 Apache POI 依赖到 pom.xml（15分钟）
- [ ] 1.2 创建 ExportController 类，定义 REST 端点（30分钟）
- [ ] 1.3 实现 ExportService.exportProjectData() 方法（2小时）
- [ ] 1.4 添加权限检查：验证用户是项目成员（1小时）
- [ ] 1.5 实现 Excel 生成逻辑（2小时）

## 2. 前端实现

- [ ] 2.1 在项目详情页添加"导出"按钮（30分钟）
- [ ] 2.2 实现导出 API 调用（30分钟）
- [ ] 2.3 实现文件下载逻辑（1小时）
- [ ] 2.4 添加加载状态和错误处理（1小时）

## 3. 测试

- [ ] 3.1 编写 ExportService 单元测试（1小时）
- [ ] 3.2 编写 ExportController 集成测试（1小时）
- [ ] 3.3 手动测试：小文件（<100行）（30分钟）
- [ ] 3.4 手动测试：大文件（1000+行）（30分钟）
- [ ] 3.5 手动测试：权限检查（30分钟）

## 4. 文档

- [ ] 4.1 更新 API 文档（30分钟）
- [ ] 4.2 更新用户手册（30分钟）

8. 及时归档

完成变更后立即归档：

# 实施完成
/opsx:apply add-project-export

# 验证无误
/opsx:verify add-project-export

# 立即归档
/opsx:archive add-project-export

归档的价值：

  • 📚 保留决策历史
  • 🔍 方便未来查阅"为什么这样做"
  • 🧹 保持活跃变更目录整洁
  • 📖 新成员可以通过归档了解系统演进

9. 与 Git 配合使用

推荐工作流：

# 1. 创建功能分支
git checkout -b feature/add-project-export

# 2. 创建 OpenSpec 变更
/opsx:new add-project-export
# [创建各个工件]

# 3. 提交工件到 Git
git add openspec/changes/add-project-export/
git commit -m "docs: add openspec artifacts for project export feature"

# 4. 实施功能
/opsx:apply add-project-export

# 5. 提交代码
git add .
git commit -m "feat: add project data export feature"

# 6. 归档变更
/opsx:archive add-project-export

# 7. 提交归档
git add openspec/changes/archive/
git commit -m "docs: archive add-project-export"

# 8. 合并到主分支
git checkout main
git merge feature/add-project-export

好处：

  • 工件和代码版本同步
  • 代码审查时可以参考工件
  • 历史记录完整清晰

❓ 常见问题

Q1: OpenSpec 会让开发变慢吗？

A: 短期看可能稍慢，长期看会更快：

短期（首次使用）：

  • 需要学习新的工作流 ⏱️ +15分钟
  • 创建工件需要时间 ⏱️ +10-30分钟

长期（熟练后）：

  • 减少返工和重构 ⏱️ -2小时
  • 减少需求误解 ⏱️ -1小时
  • 代码审查更快 ⏱️ -30分钟
  • 新人理解更快 ⏱️ -1小时

净效果：时间投入1:5的回报

Q2: 什么规模的变更适合用 OpenSpec？

推荐使用：

  • ✅ 需要超过1小时实施的变更
  • ✅ 涉及多个文件或模块
  • ✅ 有多种实现方案可选
  • ✅ 需要团队协作的变更
  • ✅ 重要的架构决策

可以不用：

  • ❌ 修改一行代码的简单修复
  • ❌ 调整配置参数
  • ❌ 修正拼写错误
  • ❌ 纯文档更新

经验法则：

如果这个变更在3个月后你可能想不起"为什么这样做"，就应该用 OpenSpec。

Q3: 工件写得越详细越好吗？

A: 不是，要适度。

提案（Proposal）：

  • ✅ 1-2页，简明扼要
  • ❌ 不要写成长篇论文

规范（Specs）：

  • ✅ 覆盖核心场景即可
  • ❌ 不要穷尽所有边界情况

设计（Design）：

  • ✅ 记录关键决策和理由
  • ❌ 不要写实现细节

任务（Tasks）：

  • ✅ 可执行的清单
  • ❌ 不要写成详细步骤手册

原则：

写到能让3个月后的自己理解"为什么"即可，不要过度设计。

Q4: 中途发现需求变了怎么办？

A: 随时更新工件。

OpenSpec 鼓励迭代：

# 在 apply 过程中发现需求不对
/opsx:continue add-project-export

# 告诉我需求变化
您：发现权限规则不对，应该是项目负责人才能导出，不是所有成员

# 我会帮您更新工件
Claude：[更新 proposal.md]
        [更新 specs/*/spec.md]
        [更新 design.md]
        [更新 tasks.md]

        工件已更新，继续实施？

工件不是死的文档，是活的思考记录。

Q5: 团队成员不熟悉 OpenSpec 怎么办？

A: 从简单开始，逐步推广。

第1周：个人试用

/opsx:onboard  # 跑一遍教程
# 在自己的小任务上试用

第2-3周：团队试点

  • 选1-2个中型功能用 OpenSpec
  • 团队成员阅读工件，提供反馈
  • 总结经验，调整流程

第4周+：全面采用

  • 所有中型以上变更使用 OpenSpec
  • 代码审查时参考工件
  • 定期回顾归档的变更

关键：

不要强制，让大家看到价值后自然采用。

Q6: 如何处理紧急修复？

A: 紧急修复可以先修复，后补工件。

紧急流程：

# 1. 立即修复问题
git checkout -b hotfix/fix-critical-bug
# [直接修改代码]
git commit -m "hotfix: fix critical bug"
git push

# 2. 部署后补充工件（非阻塞）
/opsx:ff fix-critical-bug  # 快速模式
# 简要记录问题和解决方案
/opsx:archive fix-critical-bug

原则：

用户价值 > 流程规范。紧急时先解决问题，但事后要补充记录。

Q7: 工件和代码不一致怎么办？

A: 定期验证，及时更新。

预防：

# 实施前验证
/opsx:verify <变更名>

# 发现不一致立即更新工件

修复：

# 如果代码已经改了，工件没更新
/opsx:continue <变更名>
# 告诉我代码的实际实现
# 我会更新工件使其匹配

最佳实践：

工件是"真相的源头"，代码应该符合工件。如果代码偏离了，要么更新代码，要么更新工件并记录原因。

Q8: 可以在现有项目中使用吗？

A: 完全可以！

逐步引入：

  1. 初始化 OpenSpec

    # 项目根目录运行（需要先安装 openspec CLI）
openspec init

  2. 配置项目上下文

    • 编辑 openspec/config.yaml
    • 添加技术栈、约定、领域知识

  3. 从新功能开始

    • 不要试图为所有旧代码补工件
    • 新功能开始使用 OpenSpec
    • 大型重构时使用 OpenSpec

  4. 逐步积累

    • 随着时间推移，关键模块会有工件记录
    • 归档的变更成为项目的知识库

Q9: OpenSpec 与敏捷开发冲突吗？

A: 不冲突，反而互补。

OpenSpec 支持敏捷：

敏捷原则OpenSpec 如何支持
响应变化工件可随时更新
频繁交付快速模式支持小步快跑
团队协作工件是沟通工具
可工作的软件重点是代码，工件是辅助
简化文档只写必要的决策记录

不同点：

  • OpenSpec 鼓励"先思考再编码"
  • 但思考是快速的，不是"大设计先行"
  • 工件是轻量的，不是"重型文档"

Q10: 我应该如何开始？

A: 三步走：

# 第 1 步：运行新手引导（20分钟）
/opsx:onboard

# 第 2 步：选一个小功能试用快速模式（1小时）
/opsx:ff <简单功能>

# 第 3 步：选一个中型功能试用完整流程（半天）
/opsx:explore  # 先思考
/opsx:new <中型功能>  # 逐步创建
/opsx:apply <中型功能>  # 实施
/opsx:archive <中型功能>  # 归档

然后：

  • 在实际工作中持续使用
  • 根据团队情况调整流程
  • 享受清晰思考带来的效率提升！

📚 快速参考卡

命令速查表

命令用途示例
/opsx:explore思考和调查/opsx:explore
/opsx:new <名称>创建变更（逐步）/opsx:new add-export
/opsx:ff <名称>创建变更（快速）/opsx:ff fix-bug
/opsx:continue <名称>继续变更/opsx:continue add-export
/opsx:apply <名称>实施任务/opsx:apply add-export
/opsx:verify <名称>验证实施/opsx:verify add-export
/opsx:archive <名称>归档变更/opsx:archive add-export
/opsx:onboard新手教程/opsx:onboard

决策树

需要做一个变更
     │
     ▼
  思路清晰？
   /    \
  否     是
  │      │
  ▼      ▼
/opsx:  小变更？
explore  /    \
  │     是     否
  │     │      │
  │     ▼      ▼
  │  /opsx:ff /opsx:new
  │     │      │
  └─────┴──────┘
        │
        ▼
   /opsx:apply
        │
        ▼
   /opsx:verify
        │
        ▼
  /opsx:archive

工件内容速查

工件回答关键内容
Proposal为什么做问题、价值、范围、非目标
Specs做什么需求、场景、验收标准
Design怎么做技术方案、关键决策、理由
Tasks做哪些任务清单、顺序、验证步骤

🎓 总结

OpenSpec 是您的思考伙伴，帮助您：

  • ✅ 先思考，再编码 - 减少返工和重构
  • ✅ 记录决策 - 保留"为什么这样做"
  • ✅ 结构化规划 - 将大任务分解为小步骤
  • ✅ 知识沉淀 - 归档成为项目的决策历史

记住：

OpenSpec 不是繁文缛节，而是帮助您更清晰地思考。
工件不是目的，清晰的思考和高质量的代码才是。

📞 获取帮助

在 Claude Code 中随时使用 OpenSpec 命令，我会帮助您：

  • 探索问题和方案
  • 创建和管理变更
  • 生成高质量的工件
  • 实施和验证代码

开始您的第一个 OpenSpec 变更：

/opsx:onboard

祝您使用愉快！🚀

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

从想法到真机｜启元机器人开发者社区正式上线，面向所有具身智能创作者开放

avatar AtomGit开源社区
cover

最高赢取价值万元大奖！仓颉生态创新开发挑战赛等你来挑战

avatar AtomGit开源社区
cover

从创意画布到可编辑成片，开源 AI 正在重做视频工作流

avatar AtomGit开源社区