OpenSpec 详细使用教程

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

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


目录

  1. 概述
  2. [安装 OpenSpec CLI](#安装 OpenSpec CLI "#2-%E5%AE%89%E8%A3%85-openspec-cli")
  3. 项目初始化
  4. 项目配置
  5. 核心概念速览
  6. 标准开发流程
  7. [使用 /opsx 快捷命令](#使用 /opsx 快捷命令 "#7-%E4%BD%BF%E7%94%A8-opsx-%E5%BF%AB%E6%8D%B7%E5%91%BD%E4%BB%A4")
  8. 命令行参考
  9. 目录结构总览
  10. 最佳实践
  11. [常见问题 FAQ](#常见问题 FAQ "#11-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98-faq")

1. 概述

1.1 OpenSpec 解决什么问题?

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

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

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

1.2 核心设计原则

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

1.3 与其他 SDD 工具的对比

特性 OpenSpec Spec Kit Kiro BMad
类型 CLI 工具 CLI 工具 独立 IDE Prompt 模板库
厂商 社区开源 GitHub AWS 社区开源
侵入性 低(仅 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 安装

bash 复制代码
# 全局安装(推荐)
npm install -g @fission-ai/openspec

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

# 验证安装
openspec --version

2.3 非全局安装(隔离环境)

如果你有严格的包管理要求:

bash 复制代码
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 交互式初始化

bash 复制代码
cd my-project
openspec init

交互式流程会询问:

  1. 选择要集成的 AI 工具(多选)
  2. 确认创建目录结构

3.2 非交互式初始化(常用)

bash 复制代码
# 仅配置你用的工具
openspec init --tools claude,cursor,codebuddy

# 配置所有 25+ 工具
openspec init --tools all

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

# 完全不集成 AI 工具(手动使用 CLI)
openspec init --tools none

3.3 初始化后生成的内容

bash 复制代码
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 时会读取其中的上下文和约束。

yaml 复制代码
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 文件 内容
1 proposal proposal.md 为什么做(Why)
2 design design.md 怎么做(How)
3 specs specs/<capability>/spec.md 做什么(What)
4 tasks tasks.md 执行清单(Checklist)

5.3 Status(状态流转)

lua 复制代码
openspec status --change "<name>"
bash 复制代码
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-limitingspecs/api-rate-limiting/spec.md
  • user-authspecs/user-auth/spec.md

6. 标准开发流程

以下是一个完整的"从想法到代码"的标准流程。以一个「API 请求限流器」为例。

6.1 Step 1: 创建 Change

bash 复制代码
# 创建一个新的 change
openspec new change "api-rate-limiter"

输出:

bash 复制代码
✔ Created change 'api-rate-limiter' at openspec/changes/api-rate-limiter/

生成的初始文件:

bash 复制代码
openspec/changes/api-rate-limiter/
└── .openspec.yaml    # 元数据(schema, 创建日期)

6.2 Step 2: 编写 Proposal(为什么做)

此 artifact 回答:要解决什么问题?为什么现在做?影响范围?

bash 复制代码
# 获取 proposal 的生成指令
openspec instructions proposal --change "api-rate-limiter" --json

JSON 返回的关键内容:

  • context:你的项目上下文(config.yaml 中定义的)
  • rules:该 artifact 的特殊规则
  • template:文档结构模板
  • instruction:各章节的编写指引

按模板生成 proposal.md

markdown 复制代码
## 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 都需要------仅在以下情况创建:

  • 跨模块修改或新架构模式
  • 引入新外部依赖
  • 涉及安全、性能、数据迁移
  • 存在多种方案需要取舍
bash 复制代码
openspec instructions design --change "api-rate-limiter" --json

模板

markdown 复制代码
## Context
<!-- 背景和当前状态 -->

## Goals / Non-Goals

## Decisions
<!-- 每个技术决策 + 理由 + 替代方案 -->

## Risks / Trade-offs
<!-- [风险] → 缓解措施 -->

示例片段

markdown 复制代码
## 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

bash 复制代码
openspec instructions specs --change "api-rate-limiter" --json

Spec 格式要求

markdown 复制代码
## ADDED Requirements           # ← 新增的需求

### Requirement: <需求名称>     # ← 用 ### (3个#)
系统 SHALL ...                  # ← 用 SHALL/MUST(强制性)

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

## MODIFIED Requirements        # ← 修改已有需求
### Requirement: <原有名称>
<!-- 必须包含完整的原始内容 + 修改 -->

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

完整示例

markdown 复制代码
## 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 跟踪进度。

bash 复制代码
openspec instructions tasks --change "api-rate-limiter" --json

格式

markdown 复制代码
## 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: 检查就绪状态

bash 复制代码
openspec status --change "api-rate-limiter"
csharp 复制代码
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 开始实施:

bash 复制代码
# 使用 openspec 命令归档
openspec archive "api-rate-limiter"

实施后的归档操作:

bash 复制代码
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/ 下自动生成了:

bash 复制代码
.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 中使用

bash 复制代码
# 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 初始化和管理

bash 复制代码
# 项目初始化
openspec init [path] [options]

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

# 查看版本
openspec --version

8.2 Change 管理

bash 复制代码
# 创建新的 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 生成

bash 复制代码
# 获取某个 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(工作流模式)管理

bash 复制代码
# 创建新的项目本地模式
openspec schema init <name>

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

# 查看可用模式
openspec schema list

8.5 工具集成

bash 复制代码
# 查看当前集成的 AI 工具
openspec tools list

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

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

9. 目录结构总览

bash 复制代码
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 的"项目说明书":

yaml 复制代码
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 先自下而上探索,再自上而下设计

遇到陌生模块时:

bash 复制代码
/opsx:explore    # 让 AI 先探索已有 spec

然后再 propose。比直接拍脑袋准确得多。

10.4 Spec 是活文档

  • 归档后的 spec 可以随时被新 change MODIFIEDREMOVED
  • 不要把 spec 当一次性文档,它是可以不断演进的

10.5 tasks.md 要可验证

不好- [ ] 1.1 实现限流功能- [ ] 1.1 实现 SlidingWindowRedis 类,包含 is_allowed(key, limit, window) 方法

10.6 升级后记得 update

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

11. 常见问题 FAQ

Q1: 和 Spec Kit 有什么区别?

Spec Kit 绑 GitHub Copilot 生态,命令是 /speckit.xxxOpenSpec 工具无关,支持 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?

bash 复制代码
# 直接删除 change 目录即可
rm -rf openspec/changes/<name>

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

快速上手 5 分钟

如果你是第一次用,按这个流程走:

bash 复制代码
# 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 是一次性投资,代码质量是持续回报。

相关推荐
之歆1 小时前
Day19_LESS 完全指南——从入门到工程实践
前端·css·less
云水一下2 小时前
HTML5 从入门到精通:实战收官——从零搭建完整静态网站,综合运用所有知识
前端·html5
不总是2 小时前
Windows 系统 Node.js 免安装版(zip)安装与配置教程(2026 最新)
前端·windows·node.js
冬奇Lab2 小时前
每日一个开源项目(第105篇):Twenty - 跳出 Salesforce 的圈套,定义现代开源 CRM
前端·后端·开源
zhangyao9403303 小时前
开发pc端时,表格的高度怎么设置才能铺满页面
前端·javascript·elementui
kjs--4 小时前
浏览器书签执行脚本
前端
之歆4 小时前
Day16_JavaScript 轮播图与事件工程实战(下篇)
服务器·开发语言·前端·javascript·网络·性能优化
沄媪4 小时前
CSRF 跨站请求伪造
前端·ctf·csrf
kyriewen5 小时前
我关掉了Copilot:因为我写的代码出现在了别人的建议里
前端·javascript·ai编程