OpenSpec 是什么? ------ 一个开源的 Spec-Driven Development (SDD) 框架,负责在 AI 编码之前建立「规范层」,让你和 AI 先对齐需求再写代码。
目录
- 概述
- [安装 OpenSpec CLI](#安装 OpenSpec CLI "#2-%E5%AE%89%E8%A3%85-openspec-cli")
- 项目初始化
- 项目配置
- 核心概念速览
- 标准开发流程
- [使用 /opsx 快捷命令](#使用 /opsx 快捷命令 "#7-%E4%BD%BF%E7%94%A8-opsx-%E5%BF%AB%E6%8D%B7%E5%91%BD%E4%BB%A4")
- 命令行参考
- 目录结构总览
- 最佳实践
- [常见问题 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
交互式流程会询问:
- 选择要集成的 AI 工具(多选)
- 确认创建目录结构
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-limiting→specs/api-rate-limiting/spec.mduser-auth→specs/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 会自动完成:
- 根据描述推导 change 名称(如
add-user-auth) openspec new change "<name>"创建 change 目录openspec status --change "<name>" --json获取 artifact 依赖关系- 按依赖顺序逐 artifact 调用
openspec instructions <artifact> --json获取模板 - 读取依赖 artifact 作为上下文
- 生成每个 artifact 的内容并写入文件
- 重复直到所有
applyRequires指定的 artifact 完成 - 显示完成状态
一句代码都不用写------你只负责描述需求和 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 MODIFIED 或 REMOVED
- 不要把 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.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?
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 是一次性投资,代码质量是持续回报。