OpenSpec 新手入门教程

规范驱动的AI编码助手开发方法

什么是OpenSpec？

OpenSpec 是一个为AI编码助手设计的规范驱动开发（Spec-driven development）工具，它通过轻量级的工作流程，确保人类开发者和AI助手在编写任何代码之前就能对需求达成明确共识。

核心特点

特点	描述
🚀 轻量级	无需API密钥，最小化设置
🔄 现有项目优先	特别适合修改现有功能 (1→n)
📋 变更跟踪	提案、任务和规范差异的完整生命周期管理
🤖 AI工具集成	支持多种主流AI编码助手
📁 双目录结构	specs/ 存放真实规范，changes/ 存放提议变更

Github地址：https://github.com/Fission-AI/OpenSpec

为什么需要OpenSpec？

传统AI编码助手的问题

当您使用AI编码助手时，是否遇到过以下情况：

❌ AI根据模糊提示生成不符合需求的代码
❌ 遗漏重要功能要求
❌ 添加了不必要的功能
❌ 代码行为不可预测

OpenSpec的解决方案

OpenSpec通过规范驱动开发解决这些问题：

✅ 明确共识：在编码前确定所有要求
✅ 结构化变更：所有相关文档集中管理
✅ 可审查输出：AI根据明确规范生成代码
✅ 版本控制：完整追踪所有变更历史

准备工作

系统要求

Node.js >= 20.19.0
支持的AI编码助手（见支持的AI工具）

检查Node.js版本

1	node --version

如果版本不符合要求，请访问 Node.js官网更新。

快速开始

第一步：安装OpenSpec CLI

1	npm install -g @fission-ai/openspec@latest

验证安装

1	openspec --version

第二步：在项目中初始化OpenSpec

1 2	cd your-project-directory openspec init

初始化过程会：

询问您使用的AI工具（Claude Code、Cursor等）
自动配置相应的斜杠命令
创建 openspec/ 目录结构
生成 AGENTS.md 文件

第三步：验证设置

1	openspec list

💡 如果您的AI助手没有立即显示新的斜杠命令，请重启它。

核心概念

1. 双文件夹模型

OpenSpec使用两个主要目录：

openspec/
├── specs/          # 当前真理源规范
│   └── auth/
│       └── spec.md
├── changes/        # 变更提案
│   └── feature-name/
│       ├── proposal.md
│       ├── tasks.md
│       └── specs/
└── project.md      # 项目级别约定

2. 规范格式

规范使用Markdown格式，包含：

# Auth Specification

## Purpose
Authentication and session management.

## Requirements

### Requirement: User Authentication
The system SHALL issue a JWT on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

3. 变更差异（Delta格式）

变更通过”差异”格式显示：

# Delta for Auth

## ADDED Requirements        # 新功能
## MODIFIED Requirements     # 行为变更
## REMOVED Requirements      # 已废弃功能

完整工作流程

OpenSpec遵循五步工作流程：

1️⃣ 起草变更提案

1 2	# 使用AI助手或直接创建 /openspec:proposal Add profile search filters

AI会自动创建：

openspec/changes/feature-name/proposal.md - 变更说明
openspec/changes/feature-name/tasks.md - 实施任务
openspec/changes/feature-name/specs/ - 规范差异

2️⃣ 验证与审查

# 查看当前活动的变更
openspec list

# 验证规范格式
openspec validate feature-name

# 查看提案、任务和规范差异的详细信息
openspec show feature-name

3️⃣ 完善规范

与AI迭代，直到规范满足您的需求：

1
2
3

你: "能否为角色和团队过滤器添加验收标准？"
AI: 我来更新规范差异，添加角色和团队过滤器的场景。
[编辑相应文件]

4️⃣ 实施变更

当规范确认无误后，让AI开始编码：

1 2	# 开始实施 /openspec:apply feature-name

AI会按照 tasks.md 中的清单逐步实施，每完成一个任务会标记为 ✓。

5️⃣ 归档已完成的变更

1 2	# 归档完成的变更 openspec archive feature-name --yes

归档会将批准的变更合并回 openspec/specs/ 中，并移动到 archive/ 目录。

实际示例

让我们通过一个完整的示例来理解整个流程：

示例：添加双因素认证（2FA）功能

步骤1：创建变更提案

1 2	你：请为添加双因素认证创建一个OpenSpec变更提案 [或使用快捷命令：/openspec:proposal Add two-factor authentication]

步骤2：AI生成的文件结构

openspec/
├── specs/
│   └── auth/
│       └── spec.md           # 系统中已存在的认证规范
└── changes/
    └── add-2fa/              # AI 为此功能创建的整个变更结构
        ├── proposal.md       # 描述变更的原因和内容
        ├── tasks.md          # 实现此功能的任务清单
        └── specs/
            └── auth/
                └── spec.md   # 显示对认证规范的"增量"修改

步骤3：AI生成的变更增量文件

文件路径: openspec/changes/add-2fa/specs/auth/spec.md

# Delta for Auth

## 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

步骤4：AI生成的任务清单

文件路径: openspec/changes/add-2fa/tasks.md

## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table

## 2. Backend Implementation
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint

## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI

步骤5：实施与归档

# 实施变更
/openspec:apply add-2fa

# 归档完成的变更
openspec archive add-2fa --yes

支持的AI工具

原生斜杠命令支持

工具	命令
Claude Code	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
Cursor	`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`
GitHub Copilot	`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`
Amazon Q Developer	`@openspec-proposal`, `@openspec-apply`, `@openspec-archive`
Qoder (CLI)	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
CodeBuddy Code (CLI)	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
Cline	在 `.clinerules/` 目录中的规则
Factory Droid	`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`
OpenCode	`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`

AGENTS.md兼容工具

Amp
Jules
Gemini CLI
其他兼容AGENTS.md的工具

常用命令

查看和管理变更

openspec list                    # 查看所有活动变更
openspec view                    # 交互式规范仪表板
openspec show <change-name>      # 显示变更详情
openspec validate <change-name>  # 验证规范格式

归档变更

1 2	openspec archive <change-name> # 交互式归档 openspec archive <change-name> --yes # 非交互式归档

工具管理

1	openspec update # 刷新AI指导，重新生成斜杠命令

团队采用指南

1. 初始化团队项目

1 2	# 在团队仓库中运行 openspec init

2. 从新功能开始

要求团队成员将即将到来的工作作为变更提案与AI助手讨论。

3. 增量式发展

每个完成的变更都会归档到记录您系统的实时规范中。

4. 保持工具灵活性

不同团队成员可以使用Claude Code、Cursor或任何AGENTS.md兼容工具，同时共享相同的规范。

5. 工具切换

当有人切换到不同AI工具时，运行：

1	openspec update

项目上下文设置（推荐）

初始化后，建议完善项目上下文：

使用示例提示

1	请阅读 openspec/project.md，并帮助我填写关于我的项目、技术栈和约定的详细信息。

project.md 内容示例

# Project Context

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Styling: Tailwind CSS

## Code Conventions
- 使用 TypeScript 严格模式
- 组件名使用 PascalCase
- 函数名使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

常见问题

Q1: AI助手没有显示新的斜杠命令怎么办？

A: 重启您的AI编码助手，然后运行 openspec update 刷新指导。

Q2: 可以同时处理多个变更吗？

A: 是的，OpenSpec支持同时存在多个变更提案，但一次只能应用一个。

Q3: 如何修改已归档的规范？

A: 创建一个新的变更提案，通过相同的流程来更新现有规范。

Q4: OpenSpec适用于新项目吗？

A: OpenSpec特别适合修改现有功能（1→n），但也可用于新项目（0→1）。通常建议从简单功能开始。

Q5: 团队成员使用不同AI工具可以吗？

A: 可以！OpenSpec的AGENTS.md兼容性确保所有AI工具都能理解相同的规范。

Q6: 规范文件的格式要求是什么？

使用 ### Requirement: 作为标题
每个要求至少需要一个 #### Scenario: 块
在要求文本中使用 SHALL/MUST

升级和维护

升级OpenSpec

1	npm install -g @fission-ai/openspec@latest

刷新AI指导

1 2	# 在每个项目中运行 openspec update