OpenSpec 详细使用教程

Csvn
15 阅读14分钟

OpenSpec 是什么？ —— 一个开源的 Spec-Driven Development (SDD) 框架，负责在 AI 编码之前建立「规范层」，让你和 AI 先对齐需求再写代码。

官网：github.com/Fission-AI/… | 中文文档：lzw.me/docs/opensp…

目录

  1. 概述
  2. 安装 OpenSpec CLI
  3. 项目初始化
  4. 项目配置
  5. 核心概念速览
  6. 标准开发流程
  7. 使用 /opsx 快捷命令
  8. 命令行参考
  9. 目录结构总览
  10. 最佳实践
  11. 常见问题 FAQ

1. 概述

1.1 OpenSpec 解决什么问题？

用 AI 写代码时最常见的痛点：

  • "我说了要 A，AI 给了我 B"
  • 聊了几十轮，需求始终在漂移
  • 改了一个 Bug，引入三个新 Bug
  • 代码写完了，也不知道 AI 到底按照什么逻辑写的

OpenSpec 的思路：在第一行代码写出来之前，先用结构化 Spec 对齐需求。这层 Spec 是 人类 + AI 共享的事实来源（single source of truth）。

1.2 核心设计原则

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

1.3 与其他 SDD 工具的对比

特性OpenSpecSpec KitKiroBMad
类型CLI 工具CLI 工具独立 IDEPrompt 模板库
厂商社区开源GitHubAWS社区开源
侵入性低（仅 CLI）低（仅 CLI）高（换 IDE）中（模板组织）
AI 工具兼容25+Copilot 为主Kiro 独占通用 Prompt
多 Agent❌❌✅✅

1.4 支持的 AI 编码工具

OpenSpec 为以下 25+ AI 工具自动生成集成配置（slash commands / skills / rules）：

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 的集成配置
    └── ...

注意：各 .xxx/ 目录的配置是自动生成的，一般不需要手动修改。升级 CLI 后运行 openspec update 即可刷新。

4. 项目配置

4.1 config.yaml 结构

openspec/config.yaml 是项目级的全局配置，AI 生成 artifacts 时会读取其中的上下文和约束。

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 配置项说明

字段说明必填
schema工作流模式，默认 spec-driven✅
context项目技术栈、规范、领域知识等推荐填写
rules每个 artifact 类型的额外规则可选

提示：context 是 AI 理解你项目的关键入口，写得越详细，AI 生成的 artifact 越精准。

5. 核心概念速览

5.1 Change（变更）

一次 Change 代表一个独立的、可完成的功能开发或修改。例如：

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

每个 Change 位于 openspec/changes/<name>/ 目录下。

5.2 Artifact（产物）

一个 Change 包含 4 类 artifact，按依赖顺序生成：

顺序Artifact文件内容
1proposalproposal.md为什么做（Why）
2designdesign.md怎么做（How）
3specsspecs/<capability>/spec.md做什么（What）
4taskstasks.md执行清单（Checklist）

5.3 Status（状态流转）

openspec status --change "<name>"

proposal: ready → done
design:   blocked(proposal) → ready → done
specs:    blocked(proposal) → ready → done
tasks:    blocked(design, specs) → ready → done

全部 done → ✅ 可以实施（apply）

5.4 Capability（能力）

Capability 是 proposal 中定义的"能力单元"，每个 capability 对应一个 spec.md：

  • 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 回答：要解决什么问题？为什么现在做？影响范围？

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

JSON 返回的关键内容：

  • context：你的项目上下文（config.yaml 中定义的）
  • rules：该 artifact 的特殊规则
  • 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
<!-- 如需修改已有 spec，在此列出 -->

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

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

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

此 artifact 回答：技术方案、选型理由、风险评估。不是每个 change 都需要——仅在以下情况创建：

  • 跨模块修改或新架构模式
  • 引入新外部依赖
  • 涉及安全、性能、数据迁移
  • 存在多种方案需要取舍
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（做什么）

此 artifact 是 SDD 的核心——定义系统「应该做什么」，每个 requirement 对应一个可测试的场景。

Proposal 中列出的每个 capability 都需要一个 spec.md。

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 <key>` 进行限流。

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

Spec 编写规范：

规则说明
### 定义 Requirement每个 Requirement 是一个独立需求点
#### 定义 Scenario必须用 4 个 #，用 3 个会静默失败
用 SHALL/MUST表示强制性需求，避免 should/may
每个 Requirement 至少 1 个 Scenario每个 Scenario 对应一个潜在测试用例
WHEN/THEN 格式每个 Scenario 必须有 WHEN 和 THEN

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: 检查就绪状态

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）

所有 artifacts 就绪后，告诉 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 可用命令

命令功能用法示例
/opsx:propose一次性生成 proposal + design + specs + tasks/opsx:propose "添加用户认证模块"
/opsx:apply按 tasks.md 逐条实现代码/opsx:apply
/opsx:archive完成后归档/opsx:archive
/opsx:explore探索已有的 specs 和 changes/opsx:explore

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 会自动加载这些 slash commands，直接用即可。

7.3 在 Claude Code 中使用

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

7.4 在 Cursor 中使用

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

7.5 propose 的完整自

当你在 AI 工具中输入 /opsx:propose "描述" ，AI 会自动完成：

  1. 根据描述推导 change 名称（如 add-user-auth）
  2. openspec new change "<name>" 创建 change 目录
  3. openspec status --change "<name>" --json 获取 artifact 依赖关系
  4. 按依赖顺序逐 artifact 调用 openspec instructions <artifact> --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 "<name>"

# 查看 change 状态
openspec status --change "<name>"
openspec status --change "<name>" --json

# 列出所有 changes
openspec list

# 归档完成的 change
openspec archive "<name>"

8.3 Artifact 生成

# 获取某个 artifact 的生成指令（含模板、约束、依赖）
openspec instructions <artifact-id> --change "<name>"
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 <name>

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

# 查看可用模式
openspec schema list

8.5 工具集成

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

# 添加新的 AI 工具集成
openspec tools add <tool-name>

# 更新特定工具配置
openspec tools update <tool-name>

9. 目录结构总览

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: |
  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 先自下而上探索，再自上而下设计

遇到陌生模块时：

/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. 常见问题 FAQ

Q1: 和 Spec Kit 有什么区别？

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

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

可以。CLI 本质是帮你生成模板和管理依赖关系。你完全可以用手动方式在 openspec/changes/<name>/ 下按规范写 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/<name>

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

快速上手 5 分钟

如果你是第一次用，按这个流程走：

# 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 开始实施即可

核心理念一句话：OpenSpec 不是让你写更多文档，而是让 AI 在写代码之前先理解你要什么。spec 是一次性投资，代码质量是持续回报。

avatar
文章
阅读
粉丝