OpenSpec 新手入门教程

# 什么是 OpenSpec？

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

# 核心特点

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

# 为什么需要 OpenSpec？

# 传统 AI 编码助手的问题

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

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

# OpenSpec 的解决方案

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

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

# 准备工作

# 系统要求

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

# 检查 Node.js 版本

node --version

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

# 快速开始

# 第一步：安装 OpenSpec CLI

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

验证安装：

openspec --version

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

cd your-project-directory
openspec init

1
2

初始化过程会：

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

# 第三步：验证设置

openspec list

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

# 核心概念

# 1. 双文件夹模型

OpenSpec 使用两个主要目录：

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

1
2
3
4
5
6
7
8
9
10

# 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

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3. 变更差异

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

# 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

1
2
3
4
5
6
7
8
9
10

# 完整工作流程

OpenSpec 遵循四步工作流程：

# 1️⃣ 起草变更提案

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

1
2

AI 会自动创建：

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

# 2️⃣ 审查与对齐

# 查看变更详情
openspec show feature-name

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

1
2
3
4
5

与 AI 助手讨论，直到所有人同意：

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

1
2
3

# 3️⃣ 实施任务

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

1
2

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

# 4️⃣ 归档与更新规范

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

1
2

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

# 实际示例

# 示例：添加用户资料搜索过滤功能

步骤 1：创建变更提案

您：请为添加按角色和团队过滤的用户资料搜索创建一个 OpenSpec 变更提案
[或使用快捷命令：/openspec:proposal Add profile search filters]

1
2

AI 响应：

AI：我来为您创建用户资料过滤器的 OpenSpec 变更提案。
*创建 openspec/changes/add-profile-filters/ 目录，包含 proposal.md、tasks.md 和规范差异文件*

1
2

步骤 2：验证和审查

# 确认变更文件夹存在
openspec list

# 验证规范格式
openspec validate add-profile-filters

# 审查提案、任务和规范差异
openspec show add-profile-filters

1
2
3
4
5
6
7
8

步骤 3：完善规范

您：能否为角色和团队过滤器添加验收标准？

AI 更新相应的规范差异和任务列表。

步骤 4：实施变更

您：规范看起来很好，让我们实施这个变更吧。
[或使用：/openspec:apply add-profile-filters]

1
2

AI 按任务清单逐步实施，并标记完成状态。

步骤 5：归档

您：请归档这个变更
[或使用：/openspec:archive add-profile-filters]

1
2

# 支持的 AI 工具

# 原生斜杠命令支持

工具	支持状态
Claude Code	✅ 原生支持
Cursor	✅ 原生支持
Windsurf	✅ 原生支持
Goose	✅ 原生支持
Aider	✅ 原生支持

# AGENTS.md 兼容工具

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

# 常用命令

# 查看和管理变更

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

1
2
3
4

# 归档变更

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

1
2

# 工具管理

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

# 团队采用指南

# 1. 初始化团队项目

# 在团队仓库中运行
openspec init

1
2

# 2. 从新功能开始

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

# 3. 增量式发展

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

# 4. 保持工具灵活性

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

# 5. 工具切换

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

openspec update

# 项目上下文设置（可选但推荐）

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

# 使用示例提示

请阅读 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

## Architecture Patterns
- 采用组件化设计
- 前后端分离
- RESTful API 设计
- 响应式设计原则

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 常见问题

# Q: OpenSpec 与其他规范工具的区别？

OpenSpec 专为 AI 编码助手设计，强调：

轻量级设置（无需 API 密钥）
与 AI 工具的深度集成
变更驱动的规范管理

# Q: 适合什么类型的项目？

特别适合：

现有项目的功能迭代（1→n）
需要多轮讨论的复杂变更
团队协作的规范管理

# Q: 如何处理多个并行变更？

每个变更独立存在于 openspec/changes/ 目录下，可以并行处理，归档时自动合并。

# 参考链接

OpenSpec 官方文档
规范驱动开发介绍 (opens new window)

# 规范文件理解

# Delta 格式

差异文件显示规范如何变化：

## ADDED Requirements      # 新功能
## MODIFIED Requirements    # 行为变更（包含完整更新文本）
## REMOVED Requirements     # 已废弃功能

1
2
3

# 格式要求

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

# 升级和维护

# 升级 OpenSpec

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

# 刷新 AI 指导

# 在每个项目中运行
openspec update

1
2

# 常见问题

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

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

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

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

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

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

# Q4: OpenSpec 适用于绿地项目吗？

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

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

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

# 与其他工具对比

# vs. 没有规范

方式	特点
传统方式	AI 根据模糊提示生成代码，常常遗漏要求或添加不必要功能
OpenSpec	通过明确规范带来可预测性

# vs. Spec Kit

工具	适用场景
Spec Kit	适合 0→1 新功能项目，但设置较重
OpenSpec	在修改现有行为和跨多规范更新时表现更优

# vs. Kiro (AWS)

工具	特点
Kiro	功能强大但锁定 IDE 和 Claude 模型
OpenSpec	支持您已有的多种 AI 工具

# 社区和支持

资源	链接
官方网站	https://openspec.dev/
GitHub 仓库	https://github.com/Fission-AI/OpenSpec
Discord 社区	https://discord.gg/YctCnvvshC
NPM 包	https://www.npmjs.com/package/@fission-ai/openspec

# 总结

OpenSpec 通过轻量级但结构化的规范驱动开发方法，成功解决了 AI 编码助手的不可预测性问题。无论您是个人开发者还是团队协作，OpenSpec 都能帮助您：

✅ 提高开发效率：减少因需求不明确导致的返工
✅ 确保代码质量：AI 根据明确规范生成可预测的代码
✅ 改善团队协作：所有人共享相同的规范理解
✅ 简化变更管理：结构化的变更追踪和归档

现在就开始使用 OpenSpec，让您的 AI 编码助手发挥最大效能！

本文整理自知乎专栏，介绍 OpenSpec 这一新兴的 AI 开发范式工具。

#OpenSpec #AI开发 #Claude #Cursor #规范驱动开发

上次更新: 2026/5/21 15:39:22

← OpenClaw 接入飞书流程 Claude Code 接入 DeepSeek 教程（CC Switch）→