Spec Kit 安装教程:正确安装 specify-cli 与 /speckit-* 命令变化

Spec Kit 是 GitHub 开源的规范驱动开发(Spec-Driven Development)工具包:先写规范,再出计划和任务,最后让 AI 编码助手按任务实现。它的命令行叫 specify,由 specify-cli 包提供。

网上很多教程还在用旧的安装命令、--ai 参数和 /speckit.specify 这类命令名,照抄经常报错。本文按官方文档整理当前的正确做法,并列出哪些东西变过。

核对时间

内容对照 Spec Kit 官方文档整理,核对日期 2026-10-26。这个项目版本更新很快,命令以你本机 specify --help 和官方文档为准。

适合谁

想在现有 AI 编码助手(Claude Code、GitHub Copilot、Gemini CLI、CodeBuddy CLI、Pi、Oh My Pi 等)里试用规范驱动流程的人。
之前按旧教程装过 Spec Kit,现在命令报错或找不到的人。

前置条件

项目	要求
系统	Linux、macOS 或 Windows(PowerShell 脚本可用,不需要 WSL)
Python	3.11 或更高
包管理器	uv(推荐)或 pipx
AI 编码助手	任意一个受支持的助手,官方文档列出数十个集成
Git	可选,只有启用 git 扩展时才需要

Spec Kit 本身不依赖 Node.js。如果你的助手是通过 npm 安装的,先看 AI Agent CLI 安装。

安装 specify-cli

方式一:从 PyPI 安装(最短)

# 推荐:uv
uv tool install specify-cli

# 或 pipx
pipx install specify-cli

# 或 pip
pip install specify-cli

固定版本:uv tool install specify-cli==0.12.11(把版本号换成发布页上的版本)。

方式二:从 GitHub 发布标签安装

官方文档把它列为推荐的可复现方式,需要先装好 uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

vX.Y.Z 换成 Releases 里的标签,开头的 v 不能省,例如 v0.12.11。

验证安装

specify version
specify self check

specify version 确认命令可用并显示版本;specify self check 只读,会告诉你有没有更新的发布。

初始化项目

specify init my-project --integration claude
cd my-project

--integration 选择你的 AI 助手,常用值有 claude、copilot、gemini、codebuddy、pi、omp。几个常用选项:

--script sh|ps|py:选择脚本类型。Windows 默认 ps,其他系统默认 sh。
--here --force:在已有的非空目录里初始化。--force 表示你已知晓合并警告,先提交或备份本地改动。
--non-interactive:用于 CI。不传 --integration 时默认选 GitHub Copilot,别被这个默认值坑到。

命令名:`/speckit-*`

初始化后,在 AI 助手的聊天框里按顺序运行这些命令,不是在终端里:

步骤	命令	作用
1	`/speckit-constitution`	写项目原则,后续步骤会据此检查,每个项目一次
2	`/speckit-specify`	用自然语言描述要做的功能,生成 `spec.md`
3	`/speckit-clarify`	对规范里的空白提问,并把答案补回规范
4	`/speckit-plan`	按你的技术栈生成 `plan.md` 等设计产物
5	`/speckit-checklist`	生成需求质量检查清单
6	`/speckit-tasks`	生成按依赖排序的 `tasks.md`
7	`/speckit-analyze`	只读,检查 `spec.md`、`plan.md`、`tasks.md` 之间的冲突和遗漏
8	`/speckit-implement`	按 `tasks.md` 依次实现
9	`/speckit-converge`	对照规范检查代码,缺口会追加成新任务;重复 implement 与 converge,直到报告 `Converged`

最短路径是 specify → plan → tasks → implement → converge,完整路径才包含 constitution、clarify、checklist 和 analyze。

你的助手里可能叫法不同

官方快速开始里的名字是带连字符的 /speckit-*(GitHub Copilot 的默认技能模式)。较早的教程和升级文档里还能看到 /speckit.specify 这种点号写法。不同助手、不同模式的调用格式不一样,以初始化后助手命令列表里实际出现的名字为准。

和旧教程相比,变了什么

旧教程里常见的做法	现在
只能 `uv tool install ... --from git+https://...`	增加了 PyPI 的 `specify-cli`,uv、pipx、pip 都能装;GitHub 标签安装仍受支持
`specify init --ai claude`	官方文档全部使用 `--integration claude`
`/speckit.specify`、`/speckit.plan`	快速开始使用 `/speckit-specify`、`/speckit-plan`,并新增 `/speckit-converge`
`/constitution` 会同步修改模板和命令文件	现在只更新 `.specify/memory/constitution.md`;要恢复旧的同步行为,运行 `specify preset add constitution-sync`
git 功能默认开启	现在是可选扩展,需要时运行 `specify extension add git`
命令根据 Git 分支判断当前功能	现在用 `.specify/feature.json` 记录当前功能目录

升级

升级命令行本身:

specify self check                 # 只读,检查有没有新版
specify self upgrade --dry-run     # 预览,不真正升级
specify self upgrade               # 升级到最新稳定版
specify self upgrade --tag vX.Y.Z  # 固定到某个标签

升级已有项目里的文件,在项目目录内运行:

specify integration status         # 查看已安装的集成和被改动过的文件
specify integration upgrade <key>  # 每个已安装的集成各运行一次
specify extension update           # 更新所有扩展

只有命令提示有本地改动的受管文件、并且你确认过差异之后,才给 specify integration upgrade 加 --force。

常见问题

command not found: uv:先安装 uv,再重新执行安装命令。
No such option: --integration:你机器上还有一份很旧的 specify(例如 0.1.6),排在 PATH 前面。用安装时的同一个工具重装,例如 uv tool install --force specify-cli,再用 specify version 确认。
装了两份:uv、pipx、pip 各装一次会留下多个副本。用同一个工具升级,不要混用。
PyPI 安装不会自动升级:装好后版本就固定了,需要用上面的升级命令更新。
在已有目录里初始化被拒绝:确认目录已提交或备份后,加 --here --force。