OpenSpec 使用最佳实践

前言

在软件开发过程中，如何将一个模糊的想法转化为可执行的任务，是每个团队都会面临的挑战。Spec-Driven Development（规范驱动开发） 是近年来兴起的一种方法论，它强调在动手编码之前，先通过结构化的规范文档明确「做什么」和「为什么做」。

OpenSpec 是这一方法论的工具实践者。它通过 proposal → specs → design → tasks 的流程，帮助开发者系统性地将想法落地为代码。本文将介绍 OpenSpec 与同类工具的核心差异、使用方法以及最佳实践。

一、OpenSpec 与同类工具对比

目前 spec-driven 领域主要有三款工具：OpenSpec、spec-kit 和 Bmad-pro。它们虽然都服务于规范驱动开发，但设计理念和功能侧重有明显差异。

1.1 核心差异对比

特性 OpenSpec spec-kit Bmad-pro
归档机制 ✅ 完成 change 后自动合并到主规范 ❌ 无 ❌ 无
独立 CLI ✅ 完整的命令行工具 ✅ 完整的命令行工具 ❌ 依赖 BMAD-Method
Schema 定制 ✅ 可自定义工作流和产物 ✅ 可自定义 ❌ 固定 schema
自动化执行 ❌ 手动触发各阶段 ❌ 手动触发 ✅ Ralph 循环自动执行
中文支持 ❌ 英文为主 ❌ 英文为主 ✅ 完整中文本地化

1.2 归档机制：OpenSpec 的独特价值

归档（Archive） 是 OpenSpec 最具特色的功能。

当完成一个 change 后，OpenSpec 可以将其中的 specs 合并到项目的持久规范目录（openspec/specs/），形成不断演进的项目文档。这意味着：

1
2
3
4
5
每个 change 的规范 ──归档──▶  项目持久规范库
                              │
                              ├── auth.md（来自 3 个 change 的合并）
                              ├── api.md（来自 5 个 change 的合并）
                              └── ...

相比之下，spec-kit 和 Bmad-pro 的规范文档在功能完成后就停留在原处，没有与项目长期规范库集成的机制。

1.3 为什么选择 OpenSpec

基于以上对比，选择 OpenSpec 的理由：

  1. 规范可累积：归档机制确保每个 change 的规范都能沉淀为项目资产
  2. 工具独立：不依赖其他框架，可以作为独立工具使用
  3. 工作流可定制：可以根据团队需求调整 schema 和产物模板
  4. 生态丰富：支持 20+ AI 编码工具的集成

二、OpenSpec 基本使用流程

2.1 核心概念

在开始使用 OpenSpec 之前，需要理解三个核心概念：

Change（变更）

Change 是 OpenSpec 的工作单元，代表一个完整的功能开发、bug 修复或重构任务。每个 change 都有独立的生命周期：创建 → 完善 → 实施 → 归档。

Artifact（产物）

Artifact 是 change 过程中产生的文档类型。OpenSpec 使用 schema 定义一个 change 需要哪些 artifacts 以及它们之间的依赖关系。

常见的 artifact 类型：

  • proposal.md：说明「为什么」要做这个变更
  • specs/**/*.md：定义「做什么」，即功能规范
  • design.md：解释「怎么做」，即技术设计
  • tasks.md：拆解为可执行的任务清单

Schema（模式）

Schema 定义了 change 的结构和流程。OpenSpec 内置了 spec-driven schema，也支持自定义 schema。

2.2 安装与初始化

1
2
3
4
5
6
# 安装（需要 Node.js 20.19.0+）
npm install -g @fission-ai/openspec@latest

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

2.3 创建 Change

使用 openspec new change 命令创建一个新的 change：

1
openspec new change "add-user-authentication"

输出示例：

1
2
- Creating change 'add-user-authentication'...
✔ Created change 'add-user-authentication' at openspec/changes/add-user-authentication/ (schema: spec-driven)

2.4 编写 Proposal

Proposal 文档回答「为什么」要做这个变更：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
## Why

当前系统缺乏用户认证，任何人都可以访问敏感数据。
我们需要在 Q2 前实现基础认证以满足合规要求。

## What Changes

- 添加邮箱密码登录
- 添加 JWT token 管理
- 添加登录状态持久化

## Capabilities

### New Capabilities

- `user-auth`: 用户认证功能

### Modified Capabilities

无

## Impact

- 新增 /api/auth/* 端点
- 新增 users 表
- 前端需要添加登录页面

2.5 编写 Specs

Specs 定义系统「应该做什么」。每个 capability 对应一个 spec 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
## ADDED Requirements

### Requirement: User can login

系统 SHALL 允许用户通过邮箱和密码登录。

#### Scenario: Successful login
- **WHEN** 用户输入正确的邮箱和密码
- **THEN** 系统跳转到首页
- **AND** 显示用户信息

#### Scenario: Invalid credentials
- **WHEN** 用户输入错误的密码
- **THEN** 系统显示错误提示
- **AND** 不跳转页面

关键点：

  • 使用 SHALL 或 MUST 表示强制要求
  • 每个 requirement 必须有至少一个 scenario
  • Scenario 使用 WHEN/THEN 格式，便于转化为测试用例

2.6 编写 Design

Design 文档解释「如何」实现，记录技术决策：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
## Context

当前系统使用 Express.js + PostgreSQL，需要添加无状态认证。

## Goals / Non-Goals

**Goals:**
- 实现邮箱密码登录
- 支持多设备同时登录

**Non-Goals:**
- OAuth 第三方登录（后续 change）
- 双因素认证（后续 change）

## Decisions

### 决策：使用 JWT 而非 Session

**背景**：需要支持多服务器部署

**选项**：JWT vs Session vs Cookie

**选择**：JWT

**理由**：无状态、易于水平扩展

**权衡**：无法主动让 token 失效，需要通过短过期时间 + Refresh Token 缓解

## Risks / Trade-offs

- **JWT 无法主动失效** → 使用 15 分钟过期时间 + Refresh Token 机制

2.7 生成 Tasks

Tasks 是可执行的任务清单：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
## 1. 准备工作

- [ ] 1.1 创建 users 表迁移文件
- [ ] 1.2 添加 bcrypt 和 jsonwebtoken 依赖

## 2. 核心实现

- [ ] 2.1 实现 hashPassword 工具函数
- [ ] 2.2 实现 generateToken 工具函数
- [ ] 2.3 实现 /api/auth/login 端点
- [ ] 2.4 添加登录状态中间件

## 3. 前端集成

- [ ] 3.1 创建 Login 页面组件
- [ ] 3.2 实现 token 存储逻辑

任务拆分原则：

  • 每个任务可以在一个工作时段内完成
  • 按依赖关系排序，基础设施优先

2.8 执行实施

使用 /opsx:apply 命令让 AI 助手按任务清单实施：

1
/opsx:apply

AI 会逐一完成任务，你只需确认每步的结果。完成一个任务后，将 - [ ] 改为 - [x]。

2.9 归档 Change

所有任务完成后，归档以保存规范：

1
openspec archive --change "add-user-authentication"

归档会将 change 的 specs 合并到 openspec/specs/ 目录，形成持久的规范文档。

三、最佳实践

3.1 Proposal 最佳实践

范围界定

  • 一个 change 聚焦于一个独立的功能或改进
  • 如果 proposal 超过 5 个 capabilities，考虑拆分
  • 如果只有 1-2 句话，可能不需要 OpenSpec

反模式

1
2
3
4
5
## Why
要做一个好的系统。

## What Changes
所有功能。

改进后

1
2
3
4
5
6
7
8
9
10
## Why

当前系统缺乏用户认证，任何人都可以访问敏感数据。
我们需要在 Q2 前实现基础认证以满足合规要求。

## What Changes

- 添加邮箱密码登录
- 添加 JWT token 管理
- 添加登录状态持久化

3.2 Specs 最佳实践

可测试性

每个 scenario 应该可以直接转化为测试用例：

1
2
3
4
#### Scenario: Password too short
- **WHEN** 用户输入 5 位密码
- **THEN** 系统拒绝注册
- **AND** 显示「密码至少 6 位」

场景覆盖

确保覆盖三种情况：

  • 正常流程（Happy Path）
  • 边界条件（Edge Cases）
  • 异常情况（Error Cases）

3.3 Design 最佳实践

记录「为什么」

Design 的核心价值不是记录「选了什么」，而是「为什么选这个」：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
### 决策：使用 PostgreSQL 而非 MongoDB

**背景**：需要存储用户关系数据

**选项**：
1. PostgreSQL - 关系型数据库
2. MongoDB - 文档数据库

**选择**：PostgreSQL

**理由**：
- 数据关系复杂，需要 JOIN
- 团队熟悉 SQL
- ACID 保证重要

**权衡**：
- 水平扩展不如 MongoDB 方便

3.4 Tasks 最佳实践

任务粒度

  • 太粗：「实现用户模块」
  • 合适：「创建 User 模型」「实现密码加密」「添加登录 API」

依赖标记

1
2
3
4
5
6
7
8
## 1. 基础设施

- [ ] 1.1 创建数据库迁移文件
- [ ] 1.2 配置环境变量

## 2. 核心功能（依赖 1.x）

- [ ] 2.1 实现登录逻辑

3.5 常见问题 FAQ

Q: OpenSpec 适合个人项目吗？

A: 适合。即使是个人项目，规范文档也能帮助你理清思路，方便未来回顾。

Q: 必须完成所有 artifacts 才能开始编码吗？

A: 不一定。OpenSpec 支持灵活工作流，可以先写 proposal 开始编码，后续补充 specs 和 design。

Q: 如何处理需求变更？

A:

  1. 小变更：直接修改对应的 spec
  2. 大变更：创建新的 change，在 proposal 中说明变更原因

Q: 归档后发现规范有问题怎么办？

A: 创建新的 change 来修正，在 proposal 中引用需要修正的规范。

总结

OpenSpec 是一个帮助开发者系统化思考和实践的工具。通过结构化的文档流程，让「想法 → 规范 → 设计 → 任务」的转化更加清晰可追溯。

OpenSpec 的独特价值：

  • 归档机制：每个 change 的规范都能沉淀为项目长期资产
  • 独立 CLI：不依赖其他框架，开箱即用
  • 工作流可定制：可以根据团队需求调整
工具使用
#OpenSpec #工作流 #开发工具 #最佳实践
OpenSpec 使用最佳实践
https://l1ushun.github.io/2026/03/16/openspec-best-practices/
作者
shun
发布于
2026年3月16日