安装配置

前置要求

• Node.js 18+ (推荐 LTS 版本)
• 以下任一 AI 编程工具：
  • Claude Code — Anthropic 的 AI 编程 CLI
  • OpenAI Codex — OpenAI 的 AI 编程代理

安装 spec-first CLI

从 npm 安装（推荐）

npm install -g spec-first

验证安装

spec-first doctor

如果安装成功，你会看到环境检查结果。

从源码安装

如果 npm 安装失败，可以从源码安装：

# 克隆仓库
git clone https://github.com/sunrain520/spec-first.git
cd spec-first

# 打包并安装
npm pack
npm install -g ./spec-first-<version>.tgz

# 刷新 shell 缓存（macOS/Linux）
hash -r

CLI 命令参考

命令	参数	描述
spec-first doctor	[--claude|--codex]	检查环境和项目状态
spec-first init	--claude 或 --codex, --force	同步命令、技能、代理到项目
spec-first clean	--claude 或 --codex	移除受管资产，保留自定义内容

--claude 和 --codex 是互斥参数，每次只能指定一个平台。

初始化项目

在目标项目中运行：

# 检查环境
spec-first doctor

# 根据 AI 工具选择初始化参数（二选一）
spec-first init --claude    # Claude Code 用户
spec-first init --codex     # OpenAI Codex 用户

这会在项目中创建 AI 工具所需的目录结构。

Claude Code 用户：

.claude/
├── commands/spec/     # 工作流命令入口
├── skills/            # 流程编排技能
├── agents/            # 专业任务代理
└── spec-first/        # 状态追踪

OpenAI Codex 用户：

.codex/
├── commands/spec/     # 工作流命令入口（格式不同）
├── skills/            # 流程编排技能
├── agents/            # 专业任务代理
└── spec-first/        # 状态追踪

使用工作流命令

启动你的 AI 工具后，可以使用以下 slash 命令：

Claude Code	Codex	说明
/spec:brainstorm	/spec:brainstorm	🧠 澄清需求
/spec:plan	/spec:plan	📋 生成计划
/spec:work	/spec:work	⚡ 执行实现
/spec:review	/spec:review	🔎 结构化评审
/spec:compound	/spec:compound	📚 知识沉淀

Slash 命令在两个平台上的名称和行为完全一致。Spec-First 自动检测当前平台并使用对应的原生交互方式。

下一步

继续阅读 快速开始，开始你的第一个工作流。