OpenSpec 安装指南
一句话总结：OpenSpec 是一个轻量级规格驱动开发框架，通过「先规划后执行」的工作流（explore → propose → apply → verify → archive）帮助 AI 编码工具构建正确的系统。
什么是 OpenSpec
OpenSpec 是一个用于创建和管理软件规格的框架。核心理念：
- Build the right thing — 通过规格明确需求
- Build it right — 通过验证确保实现符合规格
它不是一个运行时工具，而是工作流框架，通过 AI 编码工具（Claude Code、Cursor、Codex 等）的技能和命令来驱动。
安装
前置要求
| 依赖 | 版本 | 说明 |
|---|---|---|
| Node.js | v20.19.0+ | 运行 OpenSpec CLI |
| npm / pnpm / bun / yarn | — | 包管理器 |
安装方式
# npm（推荐）
npm install -g @fission-ai/openspec@latest
# pnpm
pnpm add -g @fission-ai/openspec@latest
# Homebrew（macOS/Linux）
brew install openspec
# Nix
nix profile install github:Fission-AI/OpenSpec验证安装：
openspec --version项目初始化
cd <your-project>
openspec initinit 会询问你使用哪些 AI 工具，然后生成对应的工作流文件。
生成的目录结构
openspec/
├── config.yaml # 项目配置和上下文
├── specs/ # 规格文档（初始为空）
└── changes/ # 进行中的变更（初始为空）
└── archive/ # 已完成的变更归档
工作流文件
.agents/skills/
├── openspec-explore/ # 探索问题、理解代码库
├── openspec-propose/ # 起草提案
├── openspec-apply-change/ # 实施变更任务
├── openspec-update-change/ # 修订变更计划
├── openspec-sync-specs/ # 同步规格更新
├── openspec-archive-change/ # 归档已完成变更
└── openspec-verify-change/ # 验证实现符合规格
工作流
OpenSpec 的核心工作流：
| 阶段 | 命令 | 说明 |
|---|---|---|
| explore | /opsx:explore | 探索问题、理解代码库 |
| propose | /opsx:propose | 起草 proposal.md + specs/ + design.md + tasks.md |
| apply | /opsx:apply | 按 tasks.md 逐项实施 |
| verify | /opsx:verify | 检查实现是否符合规格 |
| archive | /opsx:archive | 将完成的变更移到 archive/ |
变更提案结构
openspec/changes/<change-name>/
├── proposal.md # 提案说明（为什么做、做什么）
├── tasks.md # 任务清单（可执行）
├── design.md # 技术设计（可选）
└── specs/ # 变更涉及的规格
更新
# 更新 CLI 到最新版本
openspec update
# 刷新项目工作流文件
openspec update卸载
# 1. 移除 shell 补全
openspec completion uninstall
# 2. 卸载 CLI
npm uninstall -g @fission-ai/openspec
# 3. 删除项目中的 openspec/ 目录和 .agents/skills/openspec-*相关
- 官方文档
- GitHub 仓库
- [Quartz 5 配置指南](Quartz 5 配置指南) — 使用 OpenSpec 协助搭建的项目
状态记录
- 2026-09-29：首次记录。整理 OpenSpec 安装、初始化、工作流、目录结构。