OpenSpec 使用指南

1. 什么是 OpenSpec？

OpenSpec 是一个规范驱动开发的轻量级工具，旨在帮助开发者和 AI 在编写代码之前对齐需求、明确设计，并通过可追溯的规范变更来驱动代码实现。它通过一套结构化的工作流，让 AI 生成代码更加可控、一致且可维护。

OpenSpec 的核心思想是：

  • 先写规范，再写代码：所有变更都以规范文档（Specification）为中心。
  • 规范即真理：项目的最终规范（主规范）是唯一的真实来源。
  • 变更可追溯：每个功能点都对应一个变更记录，包含提案、任务和规范差异。

2. 核心概念

概念说明
主规范存储在 .openspec/specs/ 下，描述系统当前的真实行为。
变更一次功能开发或重构的完整记录，包含提案、任务、规范差异等。
变更 ID变更的唯一标识，通常使用 kebab-case（如 add-user-login）。
规范差异变更中 specs/ 目录下的文件，描述主规范应如何变化（增、改、删）。
任务清单将变更拆解为可执行、可验证的小步骤，AI 按步骤实现。
归档变更完成后，将其移至 archive/，并将规范差异合并到主规范。

3. 文件结构

初始化后的目录结构如下：

项目根目录/
├── .openspec/
│   ├── specs/                 # 主规范（真理库）
│   │   └── <capability>/      # 能力名称（如 auth, api）
│   │       └── spec.md        # 该能力的规范文件
│   ├── changes/               # 进行中的变更
│   │   └── <change-id>/       # 每个变更一个目录
│   │       ├── proposal.md    # 变更提案
│   │       ├── tasks.md       # 任务清单
│   │       ├── design.md      # 可选：设计文档
│   │       └── specs/         # 规范差异
│   │           └── <capability>/
│   │               └── spec.md
│   └── archive/               # 已完成变更归档
└── ...（其他项目文件）

4. 各类文档详解

4.1 proposal.md — 变更提案

作用：描述变更的背景、目标、范围和影响。

必填内容：

  • 为什么：当前存在的问题或机会。
  • 改什么：变更的具体内容（功能性或非功能性）。
  • 影响范围：影响哪些模块、能力或系统。
  • 可能的风险（可选）：实现中可能遇到的技术难点或副作用。

4.2 tasks.md — 任务清单

作用：将变更拆解为可执行的小任务，用于指导 AI 逐步实现。

格式：通常使用 Markdown 任务列表（- [ ]），每个任务应尽量原子化、可验证。

示例：

- [ ] 创建 User 模型
- [ ] 实现登录 API 端点
- [ ] 添加 JWT 验证中间件
- [ ] 编写单元测试

4.3 design.md — 设计文档（可选）

作用：当变更涉及复杂架构、技术选型或重要决策时，记录设计思路。

适用场景：

  • 引入新的第三方服务
  • 设计复杂的领域模型
  • 跨模块的架构调整

4.4 specs/ — 规范差异

作用：描述主规范应如何变化，是 OpenSpec 的核心。每个受影响的 capability 对应一个 spec.md。

文件格式：规范文件通常使用以下块标记：

  • ## ADDED：新增的需求或场景
  • ## MODIFIED：修改已有需求（需包含完整的新版本）
  • ## REMOVED：移除的需求

示例：

# Capability: Authentication

## ADDED
### Requirement: User Login
The system shall allow users to log in with email and password.

#### Scenario: Successful login
- **GIVEN** a registered user with email "user@example.com" and password "secret"
- **WHEN** the user submits valid credentials
- **THEN** the system returns a JWT token

#### Scenario: Failed login
- **GIVEN** an invalid email or password
- **WHEN** the user submits credentials
- **THEN** the system returns a 401 Unauthorized response

5. 工作流完整步骤

OpenSpec 遵循 “计划 → 实施 → 归档” 的闭环流程。

5.1 初始化（仅首次）

在项目根目录执行：

openspec init

这将创建 .openspec/ 目录结构，并生成模板文件。

5.2 开始新变更

在 AI 对话中输入（例如 Cursor、VSCode 等支持 OpenSpec 插件的编辑器）：

/opsx:new 添加用户登录功能

AI 会创建 changes/add-user-login/ 目录及基础文件。

5.3 编写规划文档

有两种方式：

  • 逐步创建：/opsx:continue
    AI 依次引导你填写 proposal.md、design.md（可选）、tasks.md、specs/ 等，每完成一个再继续下一个。
  • 一次性创建：/opsx:ff（快速创建）
    AI 一次性生成所有规划文档，适合已有明确需求的场景。

5.4 审查与调整

你可以手动修改 .md 文件，或通过对话让 AI 调整。确保：

  • proposal.md 清晰阐述了变更动机和范围。
  • tasks.md 拆解得足够细致，便于分步实施。
  • specs/ 下的规范差异格式正确，且只包含受影响的 capability。

使用以下命令检查格式：

openspec validate add-user-login

5.5 实施变更

在 AI 对话中输入：

/opsx:apply

AI 将读取 tasks.md，按顺序逐一完成任务，并在完成后自动将任务项标记为 - [x]。你可以随时暂停，AI 会记住当前进度。

5.6 验证（可选）

/opsx:verify

该命令检查代码实现是否与规范文档一致。如果发现差异，AI 会提示并建议修复。

5.7 归档变更

变更完成后，输入：

/opsx:archive

AI 会执行以下操作：

  • 将变更目录从 changes/ 移动到 archive/
  • 将 changes/<change-id>/specs/ 下的增量合并到 .openspec/specs/ 对应能力中
  • 更新主规范，使其反映最终状态

至此，一次完整的变更周期结束。

6. 命令行参考（CLI）

在终端中直接执行以下命令：

命令说明
openspec init在当前目录初始化 OpenSpec
openspec list列出所有进行中的变更
openspec show <change-id>显示变更详情（提案、任务、规范等）
openspec validate <change-id>校验变更文档格式
openspec archive <change-id>手动归档变更（通常由 AI 自动完成）
openspec help显示帮助信息

7. AI 对话命令（新版 v1.0+）

在 AI 编程助手的对话中使用（如 Cursor、VSCode 等）：

命令作用
/opsx:new创建一个新变更
/opsx:continue逐步生成规划文档
/opsx:ff快速生成所有规划文档
/opsx:apply开始实施任务
/opsx:verify验证实现与规范
/opsx:archive归档变更

注意：旧版本（1.0 以下）使用 /openspec:* 命令，请根据实际版本选择。

8. 完整示例

假设我们要为一个 Web 项目添加“用户登录”功能，完整流程如下：

8.1 初始化

openspec init

8.2 创建变更

AI 对话输入：

/opsx:new 用户登录功能

8.3 快速生成文档

/opsx:ff

AI 生成以下文件：

  • changes/add-user-login/proposal.md
  • changes/add-user-login/tasks.md
  • changes/add-user-login/specs/auth/spec.md

8.4 审查与修改

检查 proposal.md：

# Proposal: 用户登录功能

## Why
当前系统缺少用户认证机制，需要增加登录功能以保护资源。

## What
- 添加登录 API 端点 `POST /api/login`
- 实现基于 JWT 的身份验证
- 添加登录失败重试限制

## Impact
- 新增 `auth` 能力
- 影响前端登录页面和 API 网关

检查 tasks.md：

- [ ] 创建 User 模型（数据库）
- [ ] 实现 `/api/login` 路由
- [ ] 验证用户凭证
- [ ] 生成并返回 JWT
- [ ] 添加登录失败计数器
- [ ] 编写单元测试

检查 specs/auth/spec.md：

# Capability: Authentication

## ADDED
### Requirement: User Login
...

如无问题，继续。

8.5 实施

/opsx:apply

AI 逐步完成任务，并自动更新 tasks.md 的勾选状态。

8.6 验证（可选）

/opsx:verify

AI 检查代码与规范是否一致，并给出报告。

8.7 归档

/opsx:archive

AI 将变更归档，并将 specs/auth/spec.md 合并到 .openspec/specs/auth/spec.md 中。

9. 最佳实践与技巧

9.1 主规范是真理库

  • 永远不要直接编辑 .openspec/specs/ 下的文件。所有对规范的修改都必须通过变更的 specs/ 增量来驱动，由 archive 命令自动合并。

9.2 任务清单要细致

  • 将任务拆分为 5～30 分钟 可完成的小块，AI 更容易准确实现。
  • 每个任务应包含明确的验收标准（例如：“实现登录 API，返回 JWT”）。

9.3 规范差异要精准

  • 只描述变更的部分，不要复制整个规范文件。
  • 使用 ADDED、MODIFIED、REMOVED 明确标记变更类型。

9.4 复杂变更使用设计文档

  • 如果变更涉及架构调整、第三方集成或复杂算法，务必添加 design.md，记录决策过程和权衡。

9.5 及时验证

  • 在 apply 完成后，执行 verify 确保实现与规范一致，避免后期返工。

9.6 定期清理归档

  • archive/ 目录会随时间增长，可定期清理旧归档（但建议保留以备追溯）。

9.7 版本升级注意

  • 如果从旧版本升级到 1.0+，注意命令前缀从 /openspec: 变为 /opsx:。

10. 常见问题

Q1: 如何修改一个已经归档的变更？

A: 不要直接修改归档。如果需要调整已实现的功能，请创建一个新的变更，在 proposal.md 中说明“修改 XXX”，并在规范差异中使用 MODIFIED 标记。

Q2: 多个变更同时进行，它们会互相影响吗？

A: 不会。每个变更独立存在于 changes/ 目录下，直到归档时才合并到主规范。但要注意避免多个变更修改同一份规范导致冲突，需在审查时协调。

Q3: 任务清单中的任务顺序重要吗？

A: 重要。AI 会按照 tasks.md 中的顺序依次执行，所以尽量按依赖关系排列任务（例如先建模型，再写 API）。

Q4: 我可以手动执行 openspec archive 吗？

A: 可以，但通常建议使用 AI 命令 /opsx:archive，因为它会自动处理规范合并。手动执行时，需确保变更的 specs/ 内容正确。

Q5: OpenSpec 支持哪些编程语言/框架？

A: OpenSpec 本身是语言无关的，它只管理规范和文档。任何语言的项目都可以使用。

11. 总结

OpenSpec 提供了一套规范驱动开发的完整工作流，将“需求 → 设计 → 任务 → 代码 → 归档”串联起来，让 AI 生成代码更可控，也让团队协作更透明。通过遵循本指南，你可以快速上手 OpenSpec，享受规范与代码同步演进带来的效率提升。

版本信息：本指南基于 OpenSpec 1.0 及以上版本编写。

反馈与贡献：如有问题或建议，欢迎提交 Issue 或参与讨论。