OpenSpec 中文详细教程
OpenSpec 是一个 AI 原生的规范驱动开发（Spec-Driven Development）框架。它帮助你与 AI 编码助手在写代码之前先达成共识------该构建什么、为什么构建、怎么构建。
目录
- 概述
- 核心概念
- 快速安装与初始化
- 目录结构详解
- [Spec 规范格式](#Spec 规范格式 "#5-spec-%E8%A7%84%E8%8C%83%E6%A0%BC%E5%BC%8F")
- 工作流程
- 命令参考
- [CLI 命令行工具](#CLI 命令行工具 "#8-cli-%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7")
- 配置与定制
- 最佳实践
- 常见问题
1. 概述
1.1 什么是 OpenSpec？
OpenSpec 是一个轻量级的规范层，放在你的项目和 AI 编码助手之间。它的核心理念是：
css
→ fluid not rigid 灵活而非僵化
→ iterative not waterfall 迭代而非瀑布
→ easy not complex 简单而非复杂
→ built for brownfield 面向存量项目而非全新项目
→ scalable from personal projects to enterprises 从小项目到企业级都适用1.2 解决了什么问题？
AI 编码助手很强大，但当需求只存在于聊天历史中时，结果是不可预测的。OpenSpec 通过一个轻量级的规范层，让你和 AI 在写代码之前就达成一致：
- 先约定再构建 --- 人类和 AI 在代码编写前对齐规范
- 保持有序 --- 每个变更都有独立的文件夹，包含提案、规范、设计和任务
- 灵活迭代 --- 随时更新任何工件，没有僵化的阶段关卡
- 兼容多种工具 --- 支持 25+ 种 AI 编码助手
1.3 与其他方案的对比
| 方案 | 特点 |
|---|---|
| GitHub Spec Kit | 功能全面但重量级，有僵化的阶段关卡 |
| Kiro (AWS) | 功能强大但锁定在特定 IDE 和 Claude 模型 |
| 不用任何规范 | 提示词模糊，结果不可预测 |
| OpenSpec | 轻量、灵活、工具无关 |
2. 核心概念
2.1 Spec（规范）
Spec 是当前系统的行为描述，是"真相的源头"。它回答"系统当前是怎么工作的"，而不是"系统应该怎么工作"。
- 按领域组织（如
auth/、payments/、ui/） - 包含需求 （Requirements）和场景（Scenarios）
- 关注外部可观察的行为，而非内部实现细节
2.2 Change（变更）
Change 是对系统的提议修改，打包成一个文件夹，包含所有理解和实施所需的内容：
bash
openspec/changes/add-dark-mode/
├── proposal.md # 为什么做、做什么
├── design.md # 怎么做（技术方案）
├── tasks.md # 实施检查清单
├── .openspec.yaml # 变更元数据
└── specs/ # 差异规范（Delta specs）
└── ui/
└── spec.md # 相对当前 spec 的变化2.3 Delta Spec（差异规范）
Delta spec 是 OpenSpec 最关键的创新。它不是重新描述整个系统，而是只描述变化的部分：
shell
## ADDED Requirements 新增需求
## MODIFIED Requirements 修改的需求
## REMOVED Requirements 移除的需求好处：
- 清晰 --- 一眼看出具体在改什么
- 避免冲突 --- 两个变更可以修改同一个 spec 文件的不同需求
- 适合存量项目 --- 大部分工作是修改已有系统
2.4 Artifact（工件）
变更文件夹中的各类文档统称为工件，它们之间存在依赖关系：
markdown
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
为什么 什么 怎么做 执行步骤| 工件 | 作用 |
|---|---|
proposal.md |
意图、范围、总体方案 |
specs/ 中的 spec.md |
具体的行为需求变更（delta） |
design.md |
技术方案、架构决策 |
tasks.md |
实施步骤检查清单 |
2.5 Schema（模式）
Schema 定义了一个工作流包含哪些工件以及它们之间的依赖关系：
yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: []
- id: specs
generates: specs/**/*.md
requires: [proposal]
- id: design
generates: design.md
requires: [proposal]
- id: tasks
generates: tasks.md
requires: [specs, design]内建 schema：spec-driven（默认），你也可以创建自定义 schema。
3. 快速安装与初始化
3.1 安装
前提条件： Node.js 20.19.0 或更高版本
bash
npm install -g @fission-ai/openspec@latest也支持 pnpm、yarn、bun、nix，详见安装文档。
3.2 初始化项目
bash
cd your-project
openspec init初始化过程会：
- 创建
openspec/目录结构 - 询问你要配置哪些 AI 工具（Claude Code、Cursor、Windsurf 等）
- 生成对应工具的技能文件（skills）和命令文件（commands）
3.3 验证安装
bash
openspec list如果看到 Active changes: (none)，说明安装成功。
4. 目录结构详解
4.1 标准项目结构
csharp
your-project/
└── openspec/
├── specs/ # 真相源头 --- 当前系统行为
│ ├── auth/
│ │ └── spec.md
│ ├── payments/
│ │ └── spec.md
│ └── ui/
│ └── spec.md
├── changes/ # 提议的变更
│ ├── add-dark-mode/
│ │ ├── proposal.md
│ │ ├── design.md
│ │ ├── tasks.md
│ │ └── specs/
│ │ └── ui/
│ │ └── spec.md # Delta spec
│ └── archive/ # 已完成的历史变更
│ └── 2026-01-15-add-dark-mode/
└── config.yaml # 项目配置（可选）4.2 各目录/文件说明
| 路径 | 说明 |
|---|---|
specs/ |
真相源头。描述系统当前的实际行为。随着变更归档而逐步演化。 |
specs/[domain]/spec.md |
按领域组织的规范文件。每个文件专注一个能力域。 |
changes/ |
活跃的变更。每个变更一个文件夹，包含完整的提案、设计、任务和差异规范。 |
changes/[name]/proposal.md |
变更提案------为什么做、做什么、影响范围。 |
changes/[name]/design.md |
技术设计------架构决策、数据流、文件变更。 |
changes/[name]/tasks.md |
实施任务清单------带复选框的可执行步骤。 |
changes/[name]/specs/ |
差异规范------相对于当前系统的新增/修改/删除。 |
changes/archive/ |
已完成变更的归档。按日期前缀排序。 |
config.yaml |
项目配置。设置默认 schema、注入上下文和规则。 |
5. Spec 规范格式
5.1 基本结构
markdown
# Auth Specification
## Purpose
认证和会话管理。
## Requirements
### Requirement: User Authentication
系统 SHALL 在登录成功时签发 JWT。
#### Scenario: Valid credentials
- GIVEN 一个拥有有效凭证的用户
- WHEN 用户提交登录表单
- THEN 返回 JWT token
- AND 用户被重定向到 dashboard
#### Scenario: Invalid credentials
- GIVEN 无效的凭证
- WHEN 用户提交登录表单
- THEN 显示错误信息
- AND 不签发任何 token5.2 格式规则
| 元素 | 格式 | 说明 |
|---|---|---|
| 需求标题 | ### Requirement: [名称] |
唯一标识，用于程序化匹配 |
| 场景标题 | #### Scenario: [描述] |
具体行为示例 |
| 行为描述 | SHALL / MUST / SHOULD | RFC 2119 关键字 |
| 场景步骤 | GIVEN / WHEN / THEN / AND | 加粗的步骤关键字 |
5.3 Delta Spec 格式（变更差异文件）
markdown
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
系统 MUST 支持 TOTP 双因素认证。
#### Scenario: 2FA enrollment
- GIVEN 一个未启用 2FA 的用户
- WHEN 用户在设置中启用 2FA
- THEN 显示 QR 码供认证器应用配置
- AND 用户必须用验证码验证后才能激活
## MODIFIED Requirements
### Requirement: Session Timeout
系统 SHALL 在 15 分钟无活动后过期会话。
（之前：30 分钟）
## REMOVED Requirements
### Requirement: Remember Me
（已废弃，改用 2FA）5.4 归档时的合并规则
| Delta 类型 | 归档操作 |
|---|---|
| ADDED | 追加到主 spec 中 |
| MODIFIED | 替换主 spec 中同名的需求 |
| REMOVED | 从主 spec 中删除 |
6. 工作流程
6.1 默认快速路径（core 模式）
初始化后默认启用，包含 5 个命令：
bash
/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive6.2 完整工作流（扩展模式）
如需更多控制，启用扩展命令：
bash
openspec config profile
openspec update然后使用：
bash
/opsx:new ──► /opsx:ff (或 /opsx:continue) ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive6.3 完整示例：添加暗黑模式
步骤 1：提出变更
bash
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md --- 为什么做、做什么
✓ specs/ --- 需求和场景
✓ design.md --- 技术方案
✓ tasks.md --- 实施清单
准备就绪，可以实施！步骤 2：查看生成的工件
markdown
# Proposal: Add Dark Mode
## Intent
用户请求暗黑模式选项，以减少夜间使用时的眼睛疲劳。
## Scope
范围内：
- 在设置中添加主题切换
- 支持系统偏好检测
- 在 localStorage 中持久化偏好
## Approach
使用 CSS 自定义属性实现主题化，React Context 管理状态。
markdown
# Tasks
## 1. 主题基础设施
- [ ] 1.1 创建 ThemeContext（light/dark 状态）
- [ ] 1.2 添加颜色 CSS 自定义属性
- [ ] 1.3 实现 localStorage 持久化
## 2. UI 组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 将切换开关添加到设置页
## 3. 样式
- [ ] 3.1 定义暗黑主题色板
- [ ] 3.2 更新组件使用 CSS 变量步骤 3：实施
makefile
You: /opsx:apply
AI: 正在执行任务...
✓ 1.1 创建了 ThemeContext
✓ 1.2 添加了 CSS 自定义属性到 globals.css
✓ 1.3 实现了 localStorage 持久化
✓ 2.1 创建了 ThemeToggle 组件
...
所有任务完成！步骤 4：归档
bash
You: /opsx:archive
AI: Archiving add-dark-mode...
✓ 差异规范已合并到 openspec/specs/ui/spec.md
✓ 已移动到 openspec/changes/archive/2026-01-15-add-dark-mode/
完成！6.4 其他常用流程
探索性流程（需求不明确时）：
bash
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply并行变更：
bash
变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中)
│
上下文切换
│
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply批量归档：
bash
/opsx:bulk-archive7. 命令参考
7.1 默认命令（core 模式）
| 命令 | 功能 | 使用时机 |
|---|---|---|
/opsx:propose |
创建变更并一次性生成所有规划工件 | 默认入口，最快路径 |
/opsx:explore |
探索想法、调查问题、澄清需求 | 需求不明确时 |
/opsx:apply |
实施变更任务 | 准备好写代码时 |
/opsx:sync |
将差异规范合并到主规范中 | 归档前，通常由 archive 自动处理 |
/opsx:archive |
归档已完成变更 | 所有工作完成后 |
7.2 扩展命令
| 命令 | 功能 | 使用时机 |
|---|---|---|
/opsx:new |
创建变更文件夹骨架 | 想要逐步创建工件时 |
/opsx:continue |
创建下一个工件 | 想逐个审查每个工件时 |
/opsx:ff |
快进------一次性创建所有规划工件 | 需求明确时 |
/opsx:verify |
验证实施与工件的一致性 | 归档前检查 |
/opsx:bulk-archive |
批量归档多个变更 | 有多个并行变更完成时 |
/opsx:onboard |
引导式教程 | 新手学习完整流程 |
7.3 不同 AI 工具的命令语法
| 工具 | 语法 |
|---|---|
| Claude Code | /opsx:propose |
| Cursor | /opsx-propose |
| Windsurf | /opsx-propose |
| GitHub Copilot (IDE) | /opsx-propose |
| Kimi CLI | /skill:openspec-propose |
| Trae | /openspec-propose |
7.4 何时更新 vs 新建变更
更新现有变更当：
- 意图相同，执行方式优化
- 范围缩小（先做 MVP）
- 发现代码库结构与预期不符
新建变更当：
- 意图根本改变
- 范围大幅膨胀
- 原变更可以独立标记"完成"
8. CLI 命令行工具
8.1 常用 CLI 命令
| 命令 | 功能 |
|---|---|
openspec init |
初始化项目 |
openspec update |
更新 AI 工具配置 |
openspec list |
列出活跃变更 |
openspec list --specs |
列出所有规范 |
openspec show <name> |
查看变更或规范详情 |
openspec view |
交互式仪表盘 |
openspec validate <name> |
验证变更或规范 |
openspec validate --all |
验证所有内容 |
openspec status --change <name> |
查看工件进度 |
openspec archive <name> |
归档变更 |
openspec config list |
查看配置 |
openspec config set <key> <value> |
修改配置 |
openspec config profile |
配置工作流模式 |
openspec schema init <name> |
创建自定义 schema |
openspec schema fork <source> <name> |
复制现有 schema |
openspec schema validate <name> |
验证 schema |
openspec schema which <name> |
查看 schema 来源 |
openspec schemas |
列出可用 schema |
openspec feedback <message> |
提交反馈 |
openspec completion install |
安装 shell 自动补全 |
8.2 JSON 输出（用于 AI Agent 和脚本）
很多命令支持 --json 输出，方便 AI Agent 和 CI 脚本解析：
bash
openspec list --json
openspec show add-dark-mode --json
openspec validate --all --json
openspec status --change add-dark-mode --json8.3 环境变量
| 变量 | 说明 |
|---|---|
OPENSPEC_TELEMETRY=0 |
禁用匿名使用统计 |
DO_NOT_TRACK=1 |
禁用遥测 |
OPENSPEC_CONCURRENCY |
批量验证的并发数（默认 6） |
NO_COLOR |
禁用颜色输出 |
9. 配置与定制
9.1 项目配置（config.yaml）
yaml
# openspec/config.yaml
schema: spec-driven
context: |
技术栈：TypeScript, React, Node.js, PostgreSQL
API 风格：RESTful
测试：Vitest + React Testing Library
我们重视所有公共 API 的向后兼容性
rules:
proposal:
- 包含回滚计划
- 指出受影响的团队
specs:
- 使用 Given/When/Then 格式
- 引用现有模式而非从头发明9.2 自定义 Schema
创建自己的工作流：
bash
# 从零创建
openspec schema init my-workflow
# 或者 fork 默认 schema 后再修改
openspec schema fork spec-driven my-workflow
yaml
# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: 我的团队的自定义工作流
artifacts:
- id: research
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research]
- id: tasks
generates: tasks.md
requires: [proposal]9.3 三层次定制
| 层次 | 说明 | 适合 |
|---|---|---|
| 项目配置 | config.yaml 设置默认值和上下文 | 大多数团队 |
| 自定义 Schema | 定义自己的工件和依赖关系 | 有独特流程的团队 |
| 全局覆盖 | 跨项目共享 schema | 高级用户 |
9.4 社区 Schema
可安装第三方维护的 schema 包，详见自定义文档。
10. 最佳实践
10.1 变更命名
sql
好： 避免：
add-dark-mode feature-1
fix-login-redirect update
optimize-product-query changes
implement-2fa wip10.2 保持变更聚焦
一个逻辑工作单元 = 一个变更。如果同时做"添加功能 X"和"重构 Y"，考虑拆分为两个变更。
10.3 Spec 只描述行为，不描述实现
好的 Spec 内容：
- 用户或下游系统依赖的可观察行为
- 输入、输出、错误条件
- 外部约束（安全、隐私、可靠性）
避免在 Spec 中出现：
- 内部的类名、函数名
- 库或框架的选择
- 逐步实现细节
10.4 渐进式严谨
根据风险级别调整 Spec 详细程度：
轻量 Spec（默认）：
- 简短的行为优先需求
- 清晰的范围内/范围外
- 几个具体的验收条件
完整 Spec（高风险时）：
- 跨团队或跨仓库的变更
- API/契约变更、迁移、安全/隐私相关
- 歧义可能导致昂贵返工的变更
10.5 推荐使用高推理能力的模型
OpenSpec 在高推理能力模型上表现最佳：
- 规划阶段：Claude Opus 4.5、GPT 5.2
- 实施阶段：Claude Opus 4.5、GPT 5.2
10.6 上下文卫生
- 开始实施前清理上下文窗口
- 在整个会话中保持良好的上下文卫生
10.7 归档前先验证
bash
/opsx:apply ──► /opsx:verify ──► /opsx:archive/opsx:verify 从三个维度检查：
- 完整性 --- 所有任务完成、所有需求实现、场景覆盖
- 正确性 --- 实现符合 Spec 意图、边界情况已处理
- 一致性 --- 设计决策在代码中体现、模式一致
11. 常见问题
11.1 命令不被识别
markdown
可能原因：OpenSpec 未初始化或技能文件未生成
解决：
1. 确认已运行 openspec init
2. 运行 openspec update 重新生成技能文件
3. 重启 AI 工具11.2 变更未找到
markdown
解决：
1. 明确指定变更名称：/opsx:apply add-dark-mode
2. 查看活跃变更：openspec list
3. 确认你在正确的项目目录中11.3 工件生成不正确
bash
解决：
1. 在 openspec/config.yaml 中添加项目上下文
2. 添加按工件的规则提供更具体的指导
3. 提供更详细的变更描述
4. 使用 /opsx:continue 而非 /opsx:ff 以获得更多控制11.4 如何升级
bash
npm install -g @fission-ai/openspec@latest
cd your-project
openspec update # 重新生成 AI 指导文件总结
OpenSpec 的核心价值在于：先约定，再构建。
- Specs 记录系统当前行为（真相源头）
- Changes 提议对系统的修改（差异而非重述）
- 实施 让变更变为现实
- 归档 将差异合并到真相源头
- 循环往复，Specs 逐步演化
整个过程由 AI 驱动、人机协作、灵活迭代。
更多信息：GitHub 仓库 | Discord 社区 | 关注 @0xTab