5.0 OpenSpec 简介：规格驱动的 AI 开发

引言：从混乱到秩序

当你使用 AI 编程助手（如 Claude Code、Cursor、Copilot）时，是否经常遇到这样的情况：

需求迷失：聊天记录越来越长，最初的需求被淹没在对话中
范围蔓延：AI 添加了你没有要求的功能，或者遗漏了关键需求
版本混乱：不清楚当前代码实现了哪些规格，哪些还在提案阶段
协作困难：团队成员使用不同的 AI 工具，无法共享一致的开发规格

这些问题的根源在于：AI 编程助手是基于对话历史生成代码的，而对话天生就是模糊、易变、难以追踪的。

OpenSpec 正是为解决这些问题而生的。它通过引入 规格驱动开发（Spec-Driven Development） 的理念，让人类和 AI 在编写任何代码之前就达成共识，从而获得可预测、可审计的输出。

OpenSpec Dashboard

什么是 OpenSpec？

OpenSpec 是一个轻量级的规格驱动开发框架，专为 AI 编程助手设计。它的核心理念是：

先约定要构建什么，再开始编写代码。

OpenSpec 提供了一套标准化的工作流程和目录结构，让你能够：

明确意图：在结构化的规格文件中记录需求，而非散落在聊天记录中
跟踪变更：每个功能变更都有独立的提案、任务清单和规格增量
保持一致：多种 AI 工具共享同一套规格，输出行为一致
审计历史：完整的变更归档，知道系统如何一步步演进

核心特点

特性	说明
无需 API Key	纯本地工具，不依赖外部服务
轻量级	简单的目录结构和 Markdown 文件
工具无关	支持 Claude Code、Cursor、Copilot 等主流 AI 工具
增量式采用	可以从一个功能开始，逐步扩展
Brownfield 友好	特别适合改造现有项目，而非仅限于全新项目

OpenSpec vs spec-kit：两种规格驱动方法的对比

在 AI 编程领域，spec-kit 是另一个知名的规格驱动开发工具。理解两者的区别，能帮助你选择合适的工具。

设计理念的差异

spec-kit 的设计重心：
┌─────────────────────────────────┐
│         0 → 1 场景              │
│     （全新功能开发）              │
│                                 │
│  • 从空白开始构建                │
│  • 单一规格文件                  │
│  • 线性的实现流程                │
└─────────────────────────────────┘

OpenSpec 的设计重心：
┌─────────────────────────────────┐
│     0 → 1  +  1 → n 场景        │
│  （新功能 + 现有功能迭代）         │
│                                 │
│  • 支持跨规格的变更              │
│  • 双文件夹模型（specs + changes）│
│  • 完整的变更生命周期管理         │
└─────────────────────────────────┘

详细对比

对比维度	spec-kit	OpenSpec
适用场景	全新功能（0→1）	新功能 + 迭代改进（0→1 + 1→n）
规格存储	单一规格目录	双文件夹：`specs/`（当前真相）+ `changes/`（提案变更）
变更追踪	较弱	强大：提案、任务、设计、增量规格一体化
跨规格更新	困难	原生支持，一个变更可影响多个规格
归档机制	无	完整的归档流程，变更自动合并到主规格
AI 工具支持	有限	广泛：20+ AI 工具原生支持
学习曲线	较平缓	稍陡（但功能更强）

何时选择 spec-kit？

你正在开发一个全新的、独立的功能
项目规模较小，规格间依赖少
团队刚开始尝试规格驱动开发
不需要复杂的变更管理流程

何时选择 OpenSpec？

项目已有一定规模，需要迭代现有功能
一个需求变更可能涉及多个模块/规格
团队使用多种 AI 工具，需要统一的规格标准
需要完整的变更追踪和审计能力
重视 Brownfield（棕地）开发场景

实际案例对比

假设你需要为一个现有的认证系统添加双因素认证（2FA）功能：

使用 spec-kit 的方式：

markdown

# 2FA Feature Spec

## Requirements
1. User can enable 2FA
2. OTP is required during login
3. Backup codes are provided

规格是独立的，但与现有 auth 规格的关系不明确。

使用 OpenSpec 的方式：

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 现有认证规格
└── changes/
    └── add-2fa/              # 2FA 变更提案
        ├── proposal.md       # 为什么要加 2FA
        ├── tasks.md          # 实现任务清单
        └── specs/
            └── auth/
                └── spec.md   # 对 auth 规格的增量修改

OpenSpec 清晰地表明：这是对现有 auth 规格的增量修改，而非独立功能。

OpenSpec 的核心概念

1. 双文件夹模型

OpenSpec 的核心创新是将规格分为两个目录：

openspec/
├── specs/      # 当前真相：系统已实现的功能
│   └── auth/
│       └── spec.md
│
└── changes/    # 提案变更：即将实现的功能
    ├── add-2fa/
    │   └── ...
    └── archive/    # 已完成的变更

specs/：记录系统当前的行为规格（已实现）
changes/：记录提案中的变更（待实现）
changes/archive/：记录已完成的变更（归档）

这种分离带来了清晰的状态管理：你始终知道什么是已实现的，什么是计划中的。

2. 变更生命周期

每个变更都经历完整的生命周期：

起草提案 → 审核对齐 → 批准计划 → 实现任务 → 归档更新
  Draft     Review      Approve    Implement   Archive
    │          │           │           │          │
    ▼          ▼           ▼           ▼          ▼
proposal.md  反馈迭代    确认范围    编写代码    合并到 specs/
tasks.md                                       移至 archive/
specs/*.md

3. 增量规格（Delta Specs）

OpenSpec 使用增量格式描述规格变化：

markdown

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

## MODIFIED Requirements
### Requirement: User Authentication
[完整的修改后内容]

## REMOVED Requirements
### Requirement: Legacy Login
**Reason**: 已被新认证流程取代
**Migration**: 用户将自动迁移到新流程

增量格式的好处：

清晰表明改动类型（新增/修改/删除）
便于代码审查
归档时自动合并到主规格

4. 结构化场景（Scenarios）

每个需求必须包含至少一个场景，使用标准的 BDD 风格：

markdown

### Requirement: Password Reset
The system SHALL allow users to reset their password via email.

#### Scenario: Successful reset
- **WHEN** user requests password reset with valid email
- **AND** user clicks the reset link within 24 hours
- **THEN** user can set a new password
- **AND** old password becomes invalid

#### Scenario: Expired link
- **WHEN** user clicks a reset link after 24 hours
- **THEN** system shows "Link expired" message
- **AND** user must request a new reset

场景的价值：

作为验收标准
指导测试用例编写
让 AI 理解边界条件

支持的 AI 工具

OpenSpec 支持广泛的 AI 编程助手：

原生斜杠命令支持

工具	命令格式
Claude Code	`/openspec:proposal`、`/openspec:apply`、`/openspec:archive`
Cursor	`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`
GitHub Copilot	`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`
Windsurf	`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`
Cline	工作流文件 `.clinerules/workflows/openspec-*.md`
RooCode	`/openspec-proposal`、`/openspec-apply`、`/openspec-archive`
Gemini CLI	`/openspec:proposal`、`/openspec:apply`、`/openspec:archive`

AGENTS.md 兼容

对于其他 AI 工具，OpenSpec 通过 AGENTS.md 文件提供工作流指令。AI 助手会自动读取并遵循这些指令。

快速上手

安装

bash

# 需要 Node.js >= 20.19.0
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

初始化项目

bash

cd my-project
openspec init

初始化过程会：

让你选择使用的 AI 工具
创建 openspec/ 目录结构
生成 AGENTS.md 文件
为选定的工具配置斜杠命令

创建第一个变更

bash

# 使用 AI 助手创建提案
> 创建一个 OpenSpec 变更提案，添加用户搜索过滤功能

# 或使用斜杠命令（Claude Code）
/openspec:proposal Add user search filters

查看和验证

bash

# 列出活跃的变更
openspec list

# 验证变更格式
openspec validate add-user-filters --strict

# 查看变更详情
openspec show add-user-filters

本章小结

OpenSpec 代表了 AI 辅助编程的一种成熟方法论：

规格先行：在编码前明确需求，减少返工
双文件夹模型：清晰区分已实现和待实现
变更管理：完整的提案、实现、归档流程
工具无关：支持主流 AI 编程助手

与 spec-kit 相比，OpenSpec 更适合：

现有项目的迭代开发
跨多个模块的复杂变更
需要审计和追溯的企业场景

在接下来的章节中，我们将深入学习：

5.1 OpenSpec 安装与配置
5.2 OpenSpec 核心概念详解
5.3 OpenSpec + Claude Code 工作流
5.4 OpenSpec + Cursor 工作流
5.5 OpenSpec + Claude Code + Cursor 协作最佳实践

完整示例代码

下面是一个完整的 OpenSpec 初始化和首次变更提案的示例脚本：

bash

#!/bin/bash
# OpenSpec 快速入门脚本
# 演示完整的 OpenSpec 工作流

set -e

echo "=== OpenSpec 快速入门 ==="

# 1. 检查 Node.js 版本
echo "检查 Node.js 版本..."
NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 20 ]; then
    echo "错误: 需要 Node.js >= 20.19.0"
    exit 1
fi
echo "Node.js 版本检查通过"

# 2. 安装 OpenSpec（如果未安装）
if ! command -v openspec &> /dev/null; then
    echo "安装 OpenSpec..."
    npm install -g @fission-ai/openspec@latest
fi
echo "OpenSpec 版本: $(openspec --version)"

# 3. 创建示例项目目录
PROJECT_DIR="openspec-demo"
echo "创建示例项目: $PROJECT_DIR"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"

# 4. 初始化 OpenSpec（非交互模式）
echo "初始化 OpenSpec..."
openspec init --non-interactive 2>/dev/null || openspec init

# 5. 查看创建的目录结构
echo ""
echo "=== 项目结构 ==="
find openspec -type f -name "*.md" | head -20

# 6. 手动创建一个变更提案示例
CHANGE_ID="add-user-auth"
echo ""
echo "=== 创建变更提案: $CHANGE_ID ==="

# 创建变更目录
mkdir -p "openspec/changes/$CHANGE_ID/specs/auth"

# 创建 proposal.md
cat > "openspec/changes/$CHANGE_ID/proposal.md" << 'EOF'
## Why
用户需要安全的身份认证机制来保护其账户和数据。

## What Changes
- 添加用户登录功能
- 实现 JWT 令牌认证
- 添加密码哈希存储

## Impact
- Affected specs: auth
- Affected code: src/auth/, src/middleware/
EOF

# 创建 tasks.md
cat > "openspec/changes/$CHANGE_ID/tasks.md" << 'EOF'
## 1. 数据库设置
- [ ] 1.1 创建 users 表
- [ ] 1.2 添加密码哈希字段

## 2. 后端实现
- [ ] 2.1 实现注册端点 POST /api/auth/register
- [ ] 2.2 实现登录端点 POST /api/auth/login
- [ ] 2.3 实现 JWT 中间件

## 3. 测试
- [ ] 3.1 编写认证单元测试
- [ ] 3.2 编写集成测试
EOF

# 创建规格增量
cat > "openspec/changes/$CHANGE_ID/specs/auth/spec.md" << 'EOF'
# Auth Specification Delta

## ADDED Requirements

### Requirement: User Registration
The system SHALL allow new users to create an account with email and password.

#### Scenario: Successful registration
- **WHEN** a user submits valid email and password
- **AND** the email is not already registered
- **THEN** a new user account is created
- **AND** a confirmation email is sent

#### Scenario: Duplicate email
- **WHEN** a user submits an already registered email
- **THEN** the system returns an error
- **AND** no new account is created

### Requirement: User Authentication
The system SHALL authenticate users via email/password and issue JWT tokens.

#### Scenario: Valid credentials
- **WHEN** a user submits valid credentials
- **THEN** a JWT token is returned
- **AND** the token expires in 24 hours

#### Scenario: Invalid credentials
- **WHEN** a user submits invalid credentials
- **THEN** the system returns 401 Unauthorized
- **AND** no token is issued

### Requirement: Password Security
The system MUST store passwords using bcrypt with cost factor >= 12.

#### Scenario: Password hashing
- **WHEN** a new password is stored
- **THEN** it is hashed with bcrypt
- **AND** the plain text is never stored
EOF

echo "变更提案已创建"

# 7. 验证变更
echo ""
echo "=== 验证变更 ==="
openspec validate "$CHANGE_ID" --strict || echo "验证完成（可能有警告）"

# 8. 列出活跃变更
echo ""
echo "=== 活跃变更列表 ==="
openspec list

# 9. 显示变更详情
echo ""
echo "=== 变更详情 ==="
openspec show "$CHANGE_ID" 2>/dev/null || cat "openspec/changes/$CHANGE_ID/proposal.md"

echo ""
echo "=== 完成！ ==="
echo "OpenSpec 已初始化，变更提案 '$CHANGE_ID' 已创建。"
echo ""
echo "后续步骤："
echo "1. 使用 AI 助手审核提案：'请帮我审核 $CHANGE_ID 变更提案'"
echo "2. 实现任务：'请实现 $CHANGE_ID 的任务'"
echo "3. 归档变更：openspec archive $CHANGE_ID --yes"

将上述脚本保存为 openspec-quickstart.sh，然后执行：

bash

chmod +x openspec-quickstart.sh
./openspec-quickstart.sh

这个脚本会：

检查环境依赖
安装 OpenSpec（如未安装）
创建示例项目
初始化 OpenSpec
创建一个完整的变更提案示例
验证和展示结果

运行后，你将获得一个完整配置的 OpenSpec 项目，可以立即开始使用 AI 助手进行规格驱动开发。

5.0 OpenSpec 简介：规格驱动的 AI 开发 ​

引言：从混乱到秩序 ​

什么是 OpenSpec？ ​

核心特点 ​

OpenSpec vs spec-kit：两种规格驱动方法的对比 ​

设计理念的差异 ​

详细对比 ​

何时选择 spec-kit？ ​

何时选择 OpenSpec？ ​

实际案例对比 ​

OpenSpec 的核心概念 ​

1. 双文件夹模型 ​

2. 变更生命周期 ​

3. 增量规格（Delta Specs） ​

4. 结构化场景（Scenarios） ​

支持的 AI 工具 ​

原生斜杠命令支持 ​

AGENTS.md 兼容 ​

快速上手 ​

安装 ​

初始化项目 ​

创建第一个变更 ​

查看和验证 ​

本章小结 ​

完整示例代码 ​

5.0 OpenSpec 简介：规格驱动的 AI 开发

引言：从混乱到秩序

什么是 OpenSpec？

核心特点

OpenSpec vs spec-kit：两种规格驱动方法的对比

设计理念的差异

详细对比

何时选择 spec-kit？

何时选择 OpenSpec？

实际案例对比

OpenSpec 的核心概念

1. 双文件夹模型

2. 变更生命周期

3. 增量规格（Delta Specs）

4. 结构化场景（Scenarios）

支持的 AI 工具

原生斜杠命令支持

AGENTS.md 兼容

快速上手

安装

初始化项目

创建第一个变更

查看和验证

本章小结

完整示例代码