OpenSpec 技术手册使用指南
本文档提供 OpenSpec 技术手册网站的完整使用说明
一、文档体系概览
1.1 9大主分类说明
| 分类 | 路径 | 说明 |
|---|---|---|
| 📖 入门 | /docs/Introduction/ | OpenSpec 基础概念和理念 |
| 🚀 快速开始 | /docs/Getting-Started/ | 安装、初始化、快速入门 |
| 🎯 核心概念 | /docs/Core-Concepts/ | Spec、Change、Artifact 等核心概念 |
| 📚 使用指南 | /docs/User-Guide/ | 实际使用操作指南 |
| 🔧 CLI 参考 | /docs/CLI-Reference/ | 命令行工具完整参考 |
| 🔄 工作流 | /docs/Workflows/ | 不同工作流模式 |
| 🤖 AI 工具集成 | /docs/AI-Tools/ | Claude Code、Cursor 等集成 |
| ⚙️ 高级主题 | /docs/Advanced/ | CI/CD、多语言等高级话题 |
| ❓ FAQ | /docs/FAQ/ | 常见问题解答 |
1.2 关键术语对照表
| 英文术语 | 中文术语 | 说明 |
|---|---|---|
| OpenSpec | OpenSpec | 框架名称，保持英文 |
| Spec | 规范 | 主规范定义 |
| Change | 变更 | 一次完整的变更请求 |
| Artifact | 工件 | 变更中创建的文档 |
| Delta Spec | Delta 规范 | 增量规范，显示变更 |
| Schema | Schema | 工件结构定义 |
| Workflow | 工作流 | 工作流程模式 |
| Proposal | 提案 | 变更提案文档 |
| Design | 设计 | 设计文档 |
| Tasks | 任务 | 任务清单 |
二、新手入门路径
2.1 第一次使用 OpenSpec
1. 阅读 [欢迎使用 OpenSpec](/docs/Introduction/index)
↓
2. 阅读 [为什么选择 OpenSpec](/docs/Introduction/why-openspec)
↓
3. 按照 [安装指南](/docs/Getting-Started/installation) 安装 CLI
↓
4. 按照 [快速开始](/docs/Getting-Started/quick-start) 创建第一个变更
2.2 理解核心概念
建议按顺序阅读以下文档：
- 规范 (Spec) - 了解什么是主规范
- 变更 (Change) - 了解变更管理
- 工件 (Artifact - 了解4种工件类型
- Delta 规范 - 了解增量规范格式
三、常用工作流
3.1 核心工作流（推荐）
/opsx:propose → /opsx:apply → /opsx:archive
适用于大多数场景，简洁高效。
3.2 扩展工作流
/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive
适用于需要更多规范的场景。
四、CLI 命令参考
4.1 初始化命令
# 初始化 OpenSpec
openspec init
# 使用自定义 Schema
openspec init --schema tdd
4.2 生命周期命令
# 创建变更
openspec propose <变更名称>
# 应用变更
openspec apply
# 归档变更
openspec archive
4.3 浏览命令
# 列出所有变更
openspec list
# 查看变更详情
openspec show <变更名称>
4.4 验证命令
# 验证规范
openspec validate
# 验证特定变更
openspec validate <变更名称>
五、AI 工具集成
5.1 Claude Code
在 Claude Code 中使用 /opsx:propose 命令创建变更。
5.2 Cursor
在 Cursor 中使用同样的 slash 命令。
详见 Cursor 集成
5.3 Windsurf
在 Windsurf 中使用同样的 slash 命令。
详见 Windsurf 集成
六、常见问题
Q1: 如何开始使用 OpenSpec？
详见 快速开始 文档。
Q2: OpenSpec 支持哪些 AI 工具？
支持 Claude Code、Cursor、Windsurf、GitHub Copilot 等主流 AI 编码助手。
详见 AI 工具集成 文档。
Q3: 如何自定义工作流？
使用自定义 Schema 功能，详见 自定义 Schema 文档。
Q4: 如何在 CI/CD 中集成 OpenSpec？
详见 CI/CD 集成 文档。
七、文档贡献指南
7.1 添加新文档
- 在对应的分类目录下创建
.md文件 - 确保文件以标题
#开头 - 更新
sidebars.js添加到导航
7.2 文档规范
- 使用中文标点符号
- 术语保持一致性（参考术语对照表）
- 代码块使用适当的语言标注
- 链接使用相对路径