悦书阁
liufei379
2026-07-20
目录

OpenSpec 快速入门指南

# OpenSpec 快速入门指南

OpenSpec 是一个为 AI 编码助手设计的规范驱动开发工具，通过明确的规范确保 AI 生成可预测的代码。

# 安装

# 系统要求

  • Node.js >= 20.19.0

# 全局安装

npm install -g @fission-ai/openspec@latest
1

验证安装：

openspec --version
1

# 升级到最新版本

npm install -g @fission-ai/openspec@latest
openspec update  # 刷新项目中的 AI 指导
1
2

# 全量命令表

# AI 斜杠命令（在 AI 助手中使用）

命令 说明 使用场景
/opsx:explore [topic] 探索想法，明确需求 不确定如何实现功能时
/opsx:propose <name> 创建变更提案，生成规划文档 明确需求后，开始规划
/opsx:apply [name] 实施任务，编写代码 按任务清单逐步实施
/opsx:verify [name] 验证实现是否匹配规范 实施完成后，检查质量
/opsx:archive [name] 归档变更，更新主规范 验证通过后，正式归档
/opsx:new <name> 创建新的变更脚手架 expanded profile
/opsx:continue [name] 按依赖顺序创建下一个文档 expanded profile
/opsx:ff [name] 快进创建所有规划文档 expanded profile
/opsx:bulk-archive 批量归档多个变更 expanded profile
/opsx:onboard 引导教程 expanded profile

# CLI 命令（在终端使用）

# 项目管理

命令 说明
openspec init 初始化项目
openspec init --tools claude,cursor 非交互式初始化指定工具
openspec init --tools all 初始化所有支持的工具
openspec update 更新 AI 指导文件
openspec list 查看所有变更和规范
openspec view 交互式仪表板
openspec show <name> 显示变更详情
openspec validate <name> 验证规范格式
openspec status 查看文档完成状态
openspec archive <name> 归档变更

# 配置管理

命令 说明
openspec config 查看和修改设置
openspec config profile 切换 Profile（core/expanded）

# Stores（Beta）

命令 说明
openspec store setup <id> 创建并注册 Store
openspec store register <path> 注册已有 Store
openspec store list 列出已注册的 Stores
openspec store doctor 检查 Store 健康状态

# 新项目使用流程

# 初始化项目

cd your-new-project
openspec init
1
2

初始化会创建以下结构：

openspec/
├── specs/           # 当前真理源规范
├── changes/         # 变更提案
└── config.yaml      # 项目配置

.claude/skills/      # Claude Code 技能（如果选中）
.cursor/skills/      # Cursor 技能（如果选中）
1
2
3
4
5
6
7

# 新项目开发流程图

sequenceDiagram
    autonumber
    actor 开发者
    participant AI as AI 助手
    participant OpenSpec as OpenSpec 系统
    
    Note over 开发者,OpenSpec: 📝 新项目开发流程
    
    rect rgb(225, 245, 255)
        Note right of 开发者: 1️⃣ 明确需求
        开发者->>AI: /opsx:explore [功能描述]
        AI->>AI: 分析可行方案
        AI-->>开发者: 推荐方案
        开发者->>开发者: 确认方案
    end
    
    rect rgb(227, 242, 253)
        Note right of 开发者: 2️⃣ 创建提案
        开发者->>AI: /opsx:propose <feature-name>
        AI->>OpenSpec: 创建变更目录
        OpenSpec-->>AI: 目录已创建
        AI->>OpenSpec: 生成 proposal.md
        AI->>OpenSpec: 生成 specs/
        AI->>OpenSpec: 生成 design.md
        AI->>OpenSpec: 生成 tasks.md
        AI-->>开发者: ✅ 提案已创建
    end
    
    rect rgb(232, 245, 233)
        Note right of 开发者: 3️⃣ 审查规划
        开发者->>OpenSpec: openspec show <feature-name>
        OpenSpec-->>开发者: 显示生成的文档
        开发者->>开发者: 人工审查
        alt 需要修改
            开发者->>OpenSpec: 手动修改规范
        end
    end
    
    rect rgb(255, 243, 224)
        Note right of 开发者: 4️⃣ 实施开发
        开发者->>AI: /opsx:apply <feature-name>
        AI->>OpenSpec: 读取 tasks.md
        OpenSpec-->>AI: 任务清单
        loop 逐步实施
            AI->>AI: 按任务编写代码
            AI->>OpenSpec: 标记任务完成
        end
        AI-->>开发者: ✅ 所有任务完成
    end
    
    rect rgb(225, 190, 231)
        Note right of 开发者: 5️⃣ 验证实现（可选）
        开发者->>AI: /opsx:verify <feature-name>
        AI->>AI: 检查完整性
        AI->>AI: 检查正确性
        AI->>AI: 检查一致性
        AI-->>开发者: 验证报告
    end
    
    rect rgb(200, 230, 201)
        Note right of 开发者: 6️⃣ 归档变更
        开发者->>AI: /opsx:archive <feature-name>
        AI->>OpenSpec: 同步 specs 到主规范
        OpenSpec-->>AI: 规范已更新
        AI->>OpenSpec: 移动到 archive/ 目录
        OpenSpec-->>AI: 已归档
        AI-->>开发者: ✅ 完成
    end
    
    alt 开发下一个功能
        开发者->>AI: /opsx:explore [下一个功能]
        Note over 开发者,OpenSpec: 🔄 循环：重复 1-6 步骤
    else 项目完成
        开发者->>开发者: 🎉 项目完成
    end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

# 新项目示例

# 1. 初始化项目
cd my-new-app
openspec init --tools claude

# 2. 开始第一个功能
# 在 AI 助手中：
/opsx:explore
> 我要做一个用户登录功能

/opsx:propose user-login

# 3. 查看生成的规划
openspec show user-login

# 4. 实施
/opsx:apply user-login

# 5. 验证
/opsx:verify user-login

# 6. 归档
/opsx:archive user-login

# 7. 开始下一个功能
/opsx:propose user-profile
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 已有项目使用流程

# 初始化已有项目

cd existing-project
openspec init --tools claude,cursor
1
2

OpenSpec 会：

  • 扫描现有代码结构
  • 创建 openspec/ 目录
  • 配置 AI 工具集成

# 已有项目变更流程图

sequenceDiagram
    autonumber
    actor 开发者
    participant AI as AI 助手
    participant OpenSpec as OpenSpec 系统
    participant Code as 现有代码库
    
    Note over 开发者,Code: 🔧 已有项目变更流程
    
    rect rgb(225, 245, 255)
        Note right of 开发者: 1️⃣ 理解现有代码
        开发者->>AI: /opsx:explore [要修改的功能]
        AI->>Code: 📖 读取相关文件
        Code-->>AI: 代码内容
        AI->>AI: 🔍 分析现有实现
        AI->>AI: 💡 提出修改方案
        AI->>AI: ⚠️ 评估影响范围
        AI-->>开发者: 分析报告 + 修改建议
    end
    
    rect rgb(227, 242, 253)
        Note right of 开发者: 2️⃣ 创建变更提案
        开发者->>AI: /opsx:propose <change-name>
        AI->>Code: 扫描现有结构
        Code-->>AI: 项目结构
        AI->>OpenSpec: 创建变更目录
        AI->>OpenSpec: 生成 proposal.md<br/>(变更原因和影响)
        AI->>OpenSpec: 生成 specs/<br/>(变更后的需求)
        AI->>OpenSpec: 生成 design.md<br/>(如何改造现有代码)
        AI->>OpenSpec: 生成 tasks.md<br/>(具体改动点清单)
        AI-->>开发者: ✅ 变更提案已创建
    end
    
    rect rgb(232, 245, 233)
        Note right of 开发者: 3️⃣ 审查变更计划
        开发者->>OpenSpec: openspec show <change-name>
        OpenSpec-->>开发者: 显示生成的文档
        开发者->>开发者: ❓ 检查是否遗漏现有功能
        开发者->>开发者: ❓ 检查是否影响其他模块
        开发者->>开发者: ❓ 检查是否考虑向后兼容
        alt 需要调整计划
            开发者->>OpenSpec: 修改规划文档
            开发者->>OpenSpec: openspec show <change-name>
        end
    end
    
    rect rgb(255, 243, 224)
        Note right of 开发者: 4️⃣ 实施变更
        开发者->>AI: /opsx:apply <change-name>
        AI->>OpenSpec: 读取 tasks.md
        OpenSpec-->>AI: 任务清单
        loop 逐步实施
            AI->>Code: ✏️ 修改现有文件
            Code-->>AI: 修改完成
            AI->>Code: 🎨 保持原有代码风格
            AI->>Code: 🧪 更新相关测试
            AI->>Code: 📝 更新文档
            AI->>OpenSpec: 标记任务完成
        end
        AI-->>开发者: ✅ 所有任务完成
    end
    
    rect rgb(225, 190, 231)
        Note right of 开发者: 5️⃣ 验证变更
        开发者->>AI: /opsx:verify <change-name>
        AI->>Code: 运行测试
        Code-->>AI: 测试结果
        AI->>AI: ❌ 检查是否破坏现有功能
        AI->>AI: 🔌 检查API兼容性
        AI->>AI: 📚 检查文档更新
        AI-->>开发者: 验证报告
        alt 验证失败
            开发者->>AI: 修复问题
            AI->>Code: 修复代码
            开发者->>AI: /opsx:verify <change-name>
        end
    end
    
    rect rgb(200, 230, 201)
        Note right of 开发者: 6️⃣ 归档变更
        开发者->>AI: /opsx:archive <change-name>
        AI->>OpenSpec: 更新主规范<br/>(记录变更历史)
        OpenSpec-->>AI: 规范已更新
        AI->>OpenSpec: 归档到 archive/ 目录
        OpenSpec-->>AI: 已归档
        AI-->>开发者: ✅ 完成
    end
    
    alt 继续下一个变更
        开发者->>AI: /opsx:explore [下一个变更]
        Note over 开发者,Code: 🔄 循环：重复 1-6 步骤
    else 变更完成
        开发者->>开发者: 🎉 变更完成
    end
    
    Note over 开发者,Code: 💡 建议：第一次使用先从小改动开始<br/>熟悉流程后再做大重构
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# 已有项目示例

# 1. 初始化已有项目
cd legacy-app
openspec init

# 2. 探索现有代码
# 在 AI 助手中：
/opsx:explore
> 我要给现有的用户搜索功能添加按角色过滤

AI：让我分析你的现有用户模块...
    我看到你已经有了基础搜索。有几个方案：
    1. 在现有搜索上添加过滤参数
    2. 创建独立的过滤服务
    你的用户表有 role 字段，方案 1 最简单。

# 3. 创建变更提案
/opsx:propose add-role-filter

# 4. 查看变更计划
openspec show add-role-filter

# 5. 实施变更
/opsx:apply add-role-filter

# 6. 验证
/opsx:verify add-role-filter

# 7. 归档
/opsx:archive add-role-filter
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 常见工作流对比

# 新项目 vs 已有项目

阶段 新项目 已有项目
探索 设计新功能 分析现有代码 + 设计变更
提案 从零开始规划 基于现有结构规划改动
实施 创建新文件 修改现有文件 + 保持兼容性
验证 检查功能完整性 额外检查是否破坏现有功能
归档 添加到主规范 更新主规范 + 记录变更

# 快速流程 vs 完整流程

快速流程（小改动）：
propose → apply → archive

完整流程（大功能/重构）：
explore → propose → [手动审查] → apply → verify → archive
1
2
3
4
5

# 最佳实践

# 模型选择

场景 推荐模型
规划（explore/propose） Claude Opus 4.7, Codex 5.5
实施（apply） Claude Opus 4.7, Codex 5.5
验证（verify） Claude Opus 4.7

# 工作建议

  1. 从小开始：第一次使用先做一个小功能，熟悉流程
  2. 清理上下文：开始实施前清除 AI 助手的上下文
  3. 手动审查：对于关键功能，人工审查 propose 生成的规划
  4. 增量验证：不要等所有任务完成才验证，边做边检查
  5. 及时归档：完成后立即归档，保持工作区整洁

# 团队协作

# 规范文件纳入版本控制
git add openspec/
git commit -m "feat: add user login specification"

# 每个开发者独立初始化 AI 工具
openspec init --tools claude,cursor
1
2
3
4
5
6

# 支持的 AI 工具

工具 支持状态
Claude Code ✅ 原生支持
Cursor ✅ 原生支持
Windsurf ✅ 原生支持
GitHub Copilot ✅ 原生支持
Cline ✅ 原生支持
Aider ✅ 原生支持
Continue ✅ 原生支持

更多工具：Gemini CLI, Codex CLI, Amazon Q, Kiro 等 30+ 工具。

# 常见问题

Q: AI 助手没有显示斜杠命令？
A: 重启 AI 助手，然后运行 openspec update

Q: 可以同时处理多个变更吗？
A: 可以。使用 openspec list 查看所有活动变更

Q: 如何切换到 expanded profile？
A: 运行 openspec config profile，选择 workflows，然后 openspec update

Q: 规范文件用什么格式？
A: 纯 Markdown，无需学习特殊语法

# 参考链接

资源 链接
官方网站 https://openspec.dev/
GitHub 仓库 https://github.com/Fission-AI/OpenSpec
Discord 社区 https://discord.gg/YctCnvvshC
NPM 包 https://www.npmjs.com/package/@fission-ai/openspec

# 核心命令速查

# AI 斜杠命令
/opsx:explore   # 探索想法
/opsx:propose   # 创建提案
/opsx:apply     # 实施任务
/opsx:verify    # 验证实现
/opsx:archive   # 归档变更

# CLI 命令
openspec init           # 初始化
openspec list           # 查看变更
openspec show <name>    # 查看详情
openspec update         # 更新指导
1
2
3
4
5
6
7
8
9
10
11
12

本文基于 OpenSpec 官方文档整理，专注实用流程和命令速查。

#OpenSpec#AI开发#Claude Code#Cursor#规范驱动开发
上次更新: 2026/7/20 17:55:25
Scrapling-MCP集成指南
AI开发者资源收录

← AI开发者资源收录→

最近更新
01
Star-Office-UI 部署指南 - 像素风格的 AI 办公室看板
07-21
02
Mermaid 测试页面
07-20
03
OpenSpec 与 CodeGraph 搭配使用指南
07-20
更多文章>
Theme by Vdoing | Copyright © 2022-2026 Felix