OpenSpec 新手入门教程：从零开始全面掌握使用技巧

内容导览

1. 为什么选择 OpenSpec
2. 安装 OpenSpec CLI
3. 初始化你的项目
4. 全局配置详解
5. 核心概念一览
6. 标准开发工作流
7. 用 /opsx 命令加速流程
8. 完整命令参考
9. 目录结构全景
10. 实战最佳实践
11. 常见疑问解答

1. 为什么选择 OpenSpec

1.1 OpenSpec 解决了哪些痛点？

让我们从一个真实场景切入：用 AI 写代码的开发者，常有这几个崩溃时刻。

• 明明说好做 A，AI 却给出了 B。
• 来回几十轮对话，需求像脱缰的野马。
• 修掉一个 bug，又蹦出三个新问题。
• 代码完工后，自己都不知道 AI 当初是怎么思考的。

OpenSpec 的解法很干脆：写第一行代码之前，用结构化的 Spec 把需求锁死。这套 Spec 就是人类与 AI 之间的“单一事实来源”（single source of truth），互不忽悠。

1.2 核心设计理念

整个工作流是一条清晰的链条：

人类意图 → Proposal（为什么做）
          ↓ Design（怎么做）
          ↓ Specs（做什么 → 可测试的需求）
          ↓ Tasks（实施清单 → checkbox）
          ↓ Apply（AI 逐 task 实现）
          ↓ Archive（完成后归档到规范库）

每个环节产出明确，环环相扣，层层递进。

1.3 与其他 SDD 工具横向对比

同类工具不少，定位各有侧重。直接拉表对比：

1.4 支持的 AI 编码工具阵营

OpenSpec 对 AI 工具的兼容性覆盖面极广，支持 25+ 主流工具，并为每个工具自动生成集成配置（包括斜杠命令、技能和规则）：

codebuddy, claude, cursor, github-copilot, windsurf, gemini, cline, kiro, kilocode, roocode, auggie, amazon-q, bob, codex, forgecode, continue, cospec, crush, factory, iflow, junie, lingma, opencode, pi, qoder, qwen, trae

2. 安装 OpenSpec CLI

2.1 环境要求

• Node.js 18 及以上版本
• npm 8 及以上版本

2.2 全局安装（推荐）

全局安装后，可在任意项目目录直接调用：

# 全局安装（推荐）
npm install -g @fission-ai/openspec

# 或使用 npx 临时运行
npx @fission-ai/openspec init

# 验证安装
openspec --version

2.3 隔离环境安装

如果团队有严格的包管理策略，可选择隔离安装：

cd /path/to/workspace
npm install --prefix ./tools @fission-ai/openspec

# 使用方式
NODE_PATH=./tools/node_modules node ./tools/node_modules/.bin/openspec init

3. 初始化你的项目

3.1 交互式初始化

进入项目根目录，运行初始化命令：

cd my-project
openspec init

交互流程会询问两件事：

1. 选择你要集成的 AI 工具（可多选）
2. 确认创建目录结构

3.2 非交互式初始化（常用）

跳过交互，直接指定参数：

# 仅配置你常用的工具
openspec init --tools claude,cursor,codebuddy

# 配置全量 25+ 工具
openspec init --tools all

# 跳过确认提示
openspec init --force --tools claude

# 完全不集成 AI 工具（纯 CLI 使用）
openspec init --tools none

3.3 初始化后生成的文件结构

初始化完成后，项目目录下会新增：

my-project/
├── openspec/                    # ← OpenSpec 规范仓库
│   ├── config.yaml              # 项目配置（技术栈、规范约束等）
│   ├── specs/                   # 已归档的规范库（空目录）
│   └── changes/                 # 进行中和已归档的变更
│       └── archive/             # 已完成归档的变更
│
├── .claude/                     # Claude Code 的集成配置
│   ├── commands/opsx/           # /opsx:propose, /opsx:apply 等
│   └── skills/                  # AI 技能定义
│
├── .codebuddy/                  # CodeBuddy 的集成配置
│   ├── commands/opsx/
│   └── skills/
│
├── .cursor/                     # Cursor 的集成配置
│   └── ...
│
└── .github/                     # GitHub Copilot 的集成配置
    └── ...

4. 全局配置详解

4.1 config.yaml 结构

openspec/config.yaml 是项目级全局配置，AI 在生成产物时会读取其中的上下文和约束。这相当于给每个 AI 助手一份“项目说明书”。

schema: spec-driven

# 项目上下文（AI 生成 artifact 时的背景知识）
context: |
  Tech stack: Python 3.10+, FastAPI, Milvus, Redis, MySQL, AsyncIO
  Frontend: React 18, TypeScript 5, TailwindCSS
  Principles: API降级优先, 异步优先, 中文文档和注释
  Use conventional commits

# 各 artifact 类型的规则约束（可选）
rules:
  proposal:
    - Keep proposals under 500 words
    - Always include a "Non-goals" section
  tasks:
    - Break tasks into chunks of max 2 hours

4.2 配置字段说明

5. 核心概念一览

5.1 Change（变更）

一个 Change 代表一个独立的、可完成的功能开发单元。比如：

• add-user-auth（添加用户认证）
• api-rate-limiter（API 限流器）
• fix-session-expiry（修复会话过期 bug）

每个 Change 对应 openspec/changes// 下的一个目录。

5.2 Artifact（产物）

一个 Change 包含 4 类 artifact，它们之间有严格的依赖顺序：

5.3 Status（状态流转）

通过命令查看当前 Change 的状态：

openspec status --change ""

proposal: ready → done
design: blocked(proposal) → ready → done
specs:  blocked(proposal) → ready → done
tasks:  blocked(design, specs) → ready → done
全部 done → ✅ 可以实施（apply）

所有 artifact 标记为 done 后，才能开始写代码。

5.4 Capability（能力）

Capability 是 proposal 中定义的“能力单元”，每个 capability 对应一个独立的 spec 文件：

• api-rate-limiting → specs/api-rate-limiting/spec.md
• user-auth → specs/user-auth/spec.md

6. 标准开发工作流

下面以「API 请求限流器」为例，走一遍从想法到代码的完整流程。

6.1 Step 1: 创建 Change

# 创建一个新的 change
openspec new change "api-rate-limiter"

命令执行后输出：

✔ Created change 'api-rate-limiter' at openspec/changes/api-rate-limiter/

该目录下会生成一个元数据文件：

openspec/changes/api-rate-limiter/
└── .openspec.yaml    # 元数据（schema, 创建日期）

6.2 Step 2: 编写 Proposal（为什么做）

这个 artifact 需要回答三个问题：要解决什么问题？为什么现在解决？影响范围多大？

先获取 AI 的生成指令：

# 获取 proposal 的生成指令
openspec instructions proposal --change "api-rate-limiter" --json

返回的 JSON 包含四个关键部分：context（项目上下文）、rules（特殊规则）、template（文档结构模板）和 instruction（各章节的编写指引）。

按照模板，最终产出的 proposal.md 大致如下：

## Why
当前 AI API 网关没有请求限流机制，突发高并发下可能耗尽第三方 API 配额。

## What Changes
- 新增基于 Redis 的分布式限流中间件
- 支持按 API Key / IP 维度的独立限流
- 限流触发返回 HTTP 429

## Capabilities
### New Capabilities
- `api-rate-limiting`: API 请求限流核心能力

### Modified Capabilities


## Impact
- 后端: app/middleware/ 新增 rate_limiter.py
- 配置: config.yaml 新增加 rate_limit 段
- 运维: 新增 Redis key 前缀 ratelimit:

## Non-goals
- 不实现前端限流
- 不集成第三方限流服务

6.3 Step 3: 编写 Design（怎么做）

这个 artifact 回答的是技术方案、选型理由和风险评估。注意：并非每个 change 都需要 design——仅在以下情况建议创建：

• 跨模块修改或引入新架构模式
• 引入新外部依赖
• 涉及安全、性能、数据迁移
• 存在多种方案需要权衡

同样，先获取指令：

openspec instructions design --change "api-rate-limiter" --json

模板结构如下：

## Context


## Goals / Non-Goals

## Decisions


## Risks / Trade-offs

以限流器为例，关键的决策部分可能这样写：

## Decisions
### 算法选择：滑动窗口 → 而非令牌桶
理由：滑动窗口语义匹配"每 N 秒最多 M 次"的业务模型。
替代方案：令牌桶（更平滑但配置复杂）。

### 存储方案：Redis sorted set
理由：支持精确的滑动窗口计数。
替代方案：Redis String + TTL（仅支持固定窗口）。

## Risks / Trade-offs
- [性能] 每次请求访问 Redis 引入 ~1ms 延迟
  → 使用 Pipeline 批量操作，单一中间件只做一次 Redis 交互
- [准确度] 分布式计数有 ±5% 偏差
  → 业务上不是精确计费场景，可容忍

6.4 Step 4: 编写 Specs（做什么）

这是 SDD 的核心——定义系统“应该做什么”，每个 requirement 必须对应一个可测试的场景。

openspec instructions specs --change "api-rate-limiter" --json

Spec 有严格的格式要求：

## ADDED Requirements           # ← 新增的需求
### Requirement: <需求名称>  # ← 用 ### (3个#)
系统 SHALL ...                 # ← 用 SHALL/MUST（强制性）

#### Scenario: <场景名称>    # ← 用 #### (4个#，不要用3个)
- **WHEN** <触发条件>
- **THEN** <预期结果>

## MODIFIED Requirements        # ← 修改已有需求
### Requirement: <原有名称>


## REMOVED Requirements         # ← 删除的需求
### Requirement: <名称>
**Reason**: 删除原因
**Migration**: 迁移方案

完整示例如下：

## ADDED Requirements

### Requirement: 请求限流中间件
系统 SHALL 提供一个 FastAPI 中间件，对所有 HTTP 请求进行限流检查。

#### Scenario: 正常流量通过
- **WHEN** 用户在限流窗口内请求次数未超配额
- **THEN** 请求正常传递给下游处理器

#### Scenario: 超限流量被拒绝
- **WHEN** 用户在 60s 窗口内请求超过 100 次
- **THEN** 返回 HTTP 429，响应体包含 {"error": "rate_limited", "retry_after": 30}

### Requirement: 按 API Key 限流
系统 SHALL 支持根据 Header `Authorization: Bearer ` 进行限流。

#### Scenario: 不同 API Key 独立计数
- **WHEN** API Key A 已耗尽但 Key B 仍有余额
- **THEN** Key A 返回 429，Key B 正常通过

写 spec 需要注意的规范：

6.5 Step 5: 拆解 Tasks（实施清单）

这个 artifact 是 apply 阶段的执行清单。每个 task 用 - [ ] checkbox，便于 AI 跟踪进度。

openspec instructions tasks --change "api-rate-limiter" --json

格式示例：

## 1. 基础设施准备
- [ ] 1.1 添加 Redis 异步客户端依赖
- [ ] 1.2 在 config.yaml 新增 rate_limit 配置段
- [ ] 1.3 创建 app/middleware/ 目录

## 2. 滑动窗口算法实现
- [ ] 2.1 实现 RateLimitAlgorithm 抽象基类
- [ ] 2.2 实现 SlidingWindowRedis 类
- [ ] 2.3 编写算法单元测试

## 3. 限流中间件
- [ ] 3.1 实现 RateLimiter 中间件类
- [ ] 3.2 实现多维度组合限流逻辑
- [ ] 3.3 实现 429 响应格式
- [ ] 3.4 在 FastAPI app 注册中间件

## 4. ... (其余任务组)

任务拆解的原则很明确：

• 每组任务要能在单个 session 内完成（≤2 小时）
• 按依赖关系排序（先基础设施，再核心逻辑，再测试）
• 每个 task 必须可验证——知道什么算“完成”

6.6 Step 6: 检查就绪状态

所有 artifacts 写完之后，检查一下是否全部就绪：

openspec status --change "api-rate-limiter"

输出示例：

Change: api-rate-limiter
Schema: spec-driven
Progress: 4/4 artifacts complete
[x] proposal
[x] design
[x] specs
[x] tasks
✅ All artifacts complete! Ready for implementation.

看到这个绿色的勾，说明可以进入编码阶段了。

6.7 Step 7: 实施（Apply）

所有准备就绪后，告诉 AI 开始干活：

# 使用 openspec 命令归档
openspec archive "api-rate-limiter"

实施完成后，系统会自动做归档操作：

openspec/changes/api-rate-limiter/
→ openspec/changes/archive/api-rate-limiter/   # 移动到归档
→ openspec/specs/api-rate-limiting/spec.md     # spec 合并到主规范库

7. 用 /opsx 命令加速流程

OpenSpec 为所有集成的 AI 工具生成了一组 /opsx 快捷命令。使用这些命令，你只需要用自然语言描述需求，AI 会自动完成整套 SDD 流程。

7.1 可用命令一览

7.2 在 CodeBuddy 中使用

安装 OpenSpec 之后，CodeBuddy 的 .codebuddy/commands/opsx/ 目录下会自动生成这些命令的实现文件：

.codebuddy/commands/opsx/
├── propose.md       # /opsx:propose 的实现
├── apply.md         # /opsx:apply 的实现
├── archive.md       # /opsx:archive 的实现
└── explore.md       # /opsx:explore 的实现

CodeBuddy 会自动加载这些斜杠命令，直接使用即可。

7.3 在 Claude Code 中使用

# Claude Code 中直接输入
/opsx:propose "implement user authentication with JWT"

7.4 在 Cursor 中使用

Cursor 的 .cursor/ 目录下会自动生成 rules 和 commands，在 AI Chat 中直接使用 /opsx:propose 等命令即可。

7.5 propose 的完整自

当你在 AI 工具中输入 /opsx:propose "描述" ，AI 会自动执行以下步骤：

1. 根据描述推导出 change 名称（如 add-user-auth）
2. 执行 openspec new change "" 创建 change 目录
3. 调用 openspec status --change "" --json 获取 artifact 依赖关系
4. 按依赖顺序逐个 artifact 调用 openspec instructions --json 获取模板
5. 读取已完成 artifact 作为上下文
6. 生成每个 artifact 的内容并写入文件
7. 重复直到所有 applyRequires 指定的 artifact 完成
8. 显示完成状态

一句话概括：你只需要描述需求、然后 review 产出的 artifacts，一行代码都不用写。

8. 完整命令参考

8.1 初始化和管理

# 项目初始化
openspec init [path] [options]

# 升级 CLI 后更新指令文件
openspec update [path] [options]

# 查看版本
openspec --version

8.2 Change 管理

# 创建新的 change
openspec new change ""

# 查看 change 状态
openspec status --change ""
openspec status --change "" --json

# 列出所有 changes
openspec list

# 归档完成的 change
openspec archive ""

8.3 Artifact 生成

# 获取某个 artifact 的生成指令（含模板、约束、依赖）
openspec instructions  --change ""
openspec instructions proposal --change "api-rate-limiter" --json
openspec instructions design --change "api-rate-limiter" --json
openspec instructions specs --change "api-rate-limiter" --json
openspec instructions tasks --change "api-rate-limiter" --json

8.4 Schema（工作流模式）管理

# 创建新的项目本地模式
openspec schema init 

# 从预置模式复制
openspec schema fork <source> [name]

# 查看可用模式
openspec schema list

8.5 工具集成

# 查看当前集成的 AI 工具
openspec tools list

# 添加新的 AI 工具集成
openspec tools add 

# 更新特定工具配置
openspec tools update 

9. 目录结构全景

一个完整项目在运行 OpenSpec 后的目录结构大致如下：

my-project/
│
├── openspec/
│   ├── config.yaml               # 项目全局配置
│   │
│   ├── specs/                    # 已归档的规范库（可复用）
│   │   ├── user-auth/
│   │   │   └── spec.md           # 用户认证的最终规范
│   │   └── api-rate-limiting/
│   │       └── spec.md           # API限流的最终规范
│   │
│   └── changes/                  # 变更管理
│       ├── add-oauth-login/      # 进行中：OAuth登录
│       │   ├── .openspec.yaml
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── specs/user-auth/spec.md  # 修改已有 spec 的 delta
│       │   └── tasks.md
│       │
│       ├── api-rate-limiter/     # 进行中：API限流
│       │   ├── .openspec.yaml
│       │   ├── proposal.md
│       │   ├── design.md
│       │   ├── specs/api-rate-limiting/spec.md
│       │   └── tasks.md
│       │
│       └── archive/              # 已完成归档
│           └── add-dark-mode/
│
├── .claude/                      # Claude Code 集成
│   ├── commands/opsx/            # /opsx 命令定义
│   └── skills/                   # AI skills
│
├── .codebuddy/                   # CodeBuddy 集成
│   ├── commands/opsx/
│   └── skills/
│
├── .cursor/                      # Cursor 集成
│   └── ...
│
└── .github/                      # GitHub Copilot 集成
    └── ...

10. 实战最佳实践

10.1 config.yaml 写得越详细越好

context 字段是你给 AI 的“项目说明书”，越详细越好。一个写得好的 context 能让 AI 少犯很多方向性错误：

context: |
  Tech stack: Python 3.10+, FastAPI, LangChain, Milvus, Redis, MySQL, AsyncIO
  Frontend: React 18, TypeScript 5, Vite, TailwindCSS
  AI: Multi-model API (DashScope, ai.joyone.cn, SiliconFlow)
  Principles: API降级优先, 异步优先, 中文文档和注释
  Use conventional commits
  Key conventions:
  - All async functions use async/await
  - API routes prefixed with /api/v1/
  - Redis keys prefixed with project name

10.2 小 change > 大 change

• 一个 change 最好控制在 1-3 天能完成的范围
• 超大功能拆成多个 change 串联实现
• 归档后的 spec 可以被后续 change 引用或修改

10.3 先自下而上探索，再自上而下设计

遇到不熟悉的模块时，先让 AI 探索一下已有的 spec：

/opsx:explore
# 让 AI 先探索已有 spec

看完已有信息之后再 propose，准确率会高得多。

10.4 Spec 是活文档

• 归档后的 spec 可以随时被新 change MODIFIED 或 REMOVED
• 不要把 spec 当成一次性文档，它是可以持续演进的

10.5 tasks.md 要可验证

❌ 不好的写法：- [ ] 1.1 实现限流功能
✅ 较好的写法：- [ ] 1.1 实现 SlidingWindowRedis 类，包含 is_allowed(key, limit, window) 方法

10.6 升级后记得 update

npm update @fission-ai/openspec
openspec update
# 刷新各 AI 工具的集成配置

11. 常见疑问解答

Q1: 和 Spec Kit 有什么区别？

Spec Kit 绑定 GitHub Copilot 生态，命令是 /speckit.xxx。而 OpenSpec 是工具无关的，支持 25+ AI 工具，同一套 spec 可以在 Cursor、Claude Code、CodeBuddy 之间复用，灵活性更高。

Q2: 一定要装 CLI 吗？能不能手动管理文件？

完全可以手动操作。CLI 的本质作用是帮你生成模板和管理依赖关系，你完全可以在 openspec/changes// 下手动写 markdown。不过 CLI 的好处也很明显：自动生成 artifact 依赖关系、自动计算状态流转，并且 openspec instructions 提供上下文注入，避免关键信息遗漏。

Q3: design.md 什么时候必须写？

按 OpenSpec 的建议，以下情况强烈建议写 design.md：

• 跨模块 / 跨服务修改
• 引入新外部依赖
• 涉及安全、性能、数据模型变更
• 存在多个技术方案需要决策

简单的 CRUD 功能可以跳过。

Q4: specs 和 tasks 的区别？

• specs 定义“系统该做什么”——面向验收标准，用 SHALL/MUST + Scenario 来描述
• tasks 定义“你如何把它做出来”——面向实施，用 checkbox 清单来组织

最关键的区别在于：specs 归档后可以成为可复用的规范库，而 tasks 是一次性的实施计划。

Q5: 我能在多个项目间共享 spec 吗？

目前 OpenSpec 还是项目级别的管理，不过你可以手动把 openspec/specs/ 下的通用 spec（比如 API 设计规范）复制到其他项目中使用。

Q6: 生成的 .xxx/ 目录要提交到 Git 吗？

建议提交。.claude/、.codebuddy/、.cursor/ 等是 AI 工具的配置文件，团队成员共用同一套可以保证协作时的一致性。

Q7: 怎么回退一个 change？

# 直接删除 change 目录即可
rm -rf openspec/changes/

# 如果已归档，从 archive 中删除
rm -rf openspec/changes/archive/

快速上手 5 分钟

如果你是第一次接触 OpenSpec，按这个流程走一遍就能上手：

# 1. 安装
npm install -g @fission-ai/openspec

# 2. 在项目里初始化（只配你用的工具）
cd my-project
openspec init --force --tools claude,codebuddy

# 3. 编辑 openspec/config.yaml，填上你的技术栈
# （参考上面 10.1 节的示例）

# 4. 让 AI 帮你生成第一个 change
# 在 CodeBuddy / Claude Code / Cursor 中输入：
/opsx:propose "添加用户登录功能，支持邮箱+密码，JWT 认证"

# 5. AI 自动生成 proposal → design → specs → tasks
# 你 review 后告诉 AI 开始实施即可

来源：互联网