2026 Spec Kit 完整使用教程：从安装配置到 AI 编程实战，Windows、macOS、Linux 规范驱动开发

GitHub 维护的 Spec Kit 把规范驱动开发收成可安装的命令行和一组 Agent 技能。PyPI 上的包名是 specify-cli，源码仓库是 github/spec-kit。它不替换 Cursor、Claude Code、GitHub Copilot 或 Codex，只规定这些 Agent 先写清行为，再写技术选型，最后才改仓库。2026 年 11 月，Windows 可以直接走 PowerShell 脚本，不必先装 WSL。这篇只讲安装、目录和命令顺序。规格为什么必须先于代码，见 规范驱动开发完全指南。技能文件怎么放，见 Agent Skills 使用指南。

为什么一句「帮我做个看板」已经不够

旧方式和新方式的冲突很具体。旧方式是会话优先：把目标、技术栈、目录结构一次塞进聊天，Agent 边猜边改文件，换一台机器或换一个人，上下文就断了。新方式是制品优先：原则写进 .specify/memory/constitution.md，行为和原因写进 specs/<feature>/spec.md，技术栈留到 plan.md，可执行的顺序留到 tasks.md。当前功能看 .specify/feature.json，不看你记得的上一轮对话。

这件事在 2026 年变成安装问题，而不是态度问题，有三个原因。第一，技能的调用拼法按 Agent 分叉：Cursor、Claude Code 和 Copilot 默认技能模式用 /speckit-specify，Codex 用 $speckit-specify，文档里的点号写法只是参考记法。第二，uv 和 pipx 各装一次会留下两个 specify，PATH 里的旧二进制会让 --integration 直接失败。第三，可选的 git 扩展会建编号分支，但 git checkout 本身不会切换当前功能。三件事都发生在写第一行业务代码之前。

规范驱动开发在 Spec Kit 里分成哪几层

不要把九个斜杠命令当成同一层的清单。它们落在三种制品上，而且只有两条合法路径。

原则层一个仓库做一次。/speckit-constitution 写代码质量、测试、权限和体验上的硬约束，给后面每一步当尺子。功能层每个功能一份。/speckit-specify 只回答用户能观察到什么、为什么要做；/speckit-clarify 把含糊的地方问清楚并写回规格。实现层才允许出现框架和目录。/speckit-plan 产出计划、调研、数据模型和契约；/speckit-tasks 把计划拆成有依赖顺序的任务，可并行的标 [P]；/speckit-implement 按任务改文件；/speckit-converge 拿代码和制品对账，缺什么就补任务，直到它报告 Converged。

中间还有两道质量门，不要和「代码写完了」混为一谈。/speckit-checklist 生成的是审阅者手里的需求质量清单，勾选表示这条要求写清楚了，不表示功能已经实现。/speckit-analyze 只读，报告 spec.md、plan.md、tasks.md 之间的冲突，不改文件。内建的 checklists/requirements.md 由 specify 和 clarify 维护；自定义清单归审阅者，implement 只会在未勾选时停下来问你，不会替你打勾。

短路径适合边界已经清楚的小功能：specify、plan、tasks、implement、converge。完整路径适合要上线的功能：constitution（项目里做一次）之后走 specify、clarify、plan、checklist、tasks、analyze、implement、converge。修缺陷走官方的 bug-fixing 快速入门，判断点子值不值得做走 idea assessment。两条都不是这条 SDD 路径的前置步骤。

Windows、macOS、Linux 分别怎么安装

共同前提是 Python 3.11 或更高、Git 可选（只有启用 git 扩展时才需要）、以及你真正会用来写代码的那个 Agent。推荐用 uv 做持久安装。终端里只跑 CLI；斜杠技能在 Agent 聊天里调用。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script ps

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify version
specify self check
specify init deskboard --integration cursor-agent --script sh

装完先看两件事。specify version 只证明这条命令能跑、并打印版本，不能证明它来自 PyPI 还是 GitHub。specify self check 只读，告诉你有没有更新，不会改安装。文档里的示例标签写成 v0.12.11 这种带 v 的发布号；要从源码钉死某一版，用 uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z，v 不要去掉。PyPI 钉版则是 uv tool install specify-cli==X.Y.Z。升级必须用当初那一个工具：uv tool install --force specify-cli、pipx install --force specify-cli 或 pip install --upgrade specify-cli。

已经有代码的仓库不要在脏工作区上初始化。先提交或备份，再执行 specify init --here --force --non-interactive --integration claude。--force 只表示你知道模板会并进现有文件。没有键盘的 CI 要加 --non-interactive，否则初始化会停在方向键菜单；Agent 装在另一台机器上时再加 --ignore-agent-tools，跳过本机的可执行文件检查。非交互默认集成是 Copilot，除非你写明别的 --integration。

集成键不要猜。Cursor 是 cursor-agent，不是 cursor。常见还有 claude、copilot、gemini、pi、omp、codebuddy。交互终端不传 --integration 时会让你选；脚本和管道必须显式传入。

九步命令：入口、能改什么、留给谁

下面这张表用同一套列。真正的差异在入口和执行边界，不在模型名字。

按场景选短路径还是完整路径

实操用一个只在本机跑的便签看板，不上传、第一期不做密码。三位预设成员，项目下四列：待办、进行中、待确认、完成。拖拽改列。评论只能改自己写的。specify 阶段只说这些行为和原因。plan 阶段再写「本地 SQLite，前端不用远程接口」。把数据库写进 specify，等于让第一份技术直觉变成不可挑战的需求。

推荐组合：Agent、脚本类型、隔离环境

如果你已经在 Cursor 里写这个仓库，就用 cursor-agent 加本机系统的脚本类型：Windows 用 ps，macOS 和 Linux 用 sh。初始化之后在聊天里按短路径或完整路径逐条调用，每条看完制品再下一条。不要把九个命令粘成一条提示词。

如果你主要用 Claude Code，集成键用 claude。技能很多、描述挤占上下文时，初始化加上 --integration-options="--no-model-invocation"，核心命令只在你输入 /speckit-specify 时跑。Copilot 用户保持默认技能布局即可；只有要旧的 agent 文件时才加 --commands。

implement 会改文件并执行命令。第一轮不要在存着生产密钥的笔记本上做。把仓库放到远程 Mac，看清 diff 再合回。节点怎么订，见 Mac mini 租用；预算见 套餐定价。规格里如果包含 macOS 构建或签名，把那一段任务放到真机节点，并用 OpenClaw 云端自动化 把构建和日常笔记本分开。安装失败先查 帮助中心 里的连接和系统要求，再怀疑 Spec Kit 本身。

五条会让后续全部返工的误区

1. 在 specify 里写框架和数据库。 技术栈属于 plan。规格里出现「必须用某某库」，后面的 clarify 和 analyze 都在替这个选择圆场。
2. 在终端输入 /speckit-specify。 斜杠技能只存在于 Agent 聊天。终端只跑 specify 本身。
3. 把文档点号命令贴进 Cursor。 Cursor 里的技能是 /speckit-specify。点号形式是参考记法。
4. uv 和 pipx 各装一份。 旧的 0.1.x 会报 No such option: --integration，或在 --ai 上报 No matching release asset found。先 which specify，再决定删哪一份。
5. 用 git checkout 当功能切换器。 要改 .specify/feature.json，或设置 SPECIFY_FEATURE_DIRECTORY。只换分支，命令仍会改上一份规格的目录。

七步落地

1. 安装 uv 和 specify-cli，跑 specify version 与 specify self check，确认 PATH 上只有一个二进制。
2. 按系统选 --script，按正在用的 Agent 选 --integration，执行 specify init。已有仓库先提交，再加 --here --force。
3. 在 Agent 聊天里运行一次 /speckit-constitution。只写原则：输入要校验、评论只能改作者本人、第一期不上传。
4. 用 /speckit-specify 写便签看板的行为和原因。要上线就接着 /speckit-clarify，把拖拽、权限和空项目这三处问完。
5. 规格稳定后再 /speckit-plan。然后 checklist、tasks、analyze。analyze 报冲突就改源头，不要在 implement 里打补丁。
6. 在隔离的 Mac 或干净目录运行 /speckit-implement。任务多就按阶段，不要一次吞掉整个 tasks.md。
7. 跑 /speckit-converge，直到报告 Converged。然后看 diff：有没有越出规格的文件，有没有把密钥写进仓库。

常见问题

Spec Kit 和直接在 Cursor 里聊天有什么区别？

聊天记录留在会话里，换人、换机器就丢。Spec Kit 把原则、规格、计划、任务写成仓库里的 Markdown。当前功能由 .specify/feature.json 指向，不靠你记得上一次聊了什么。

命令到底是 /speckit-specify 还是 /speckit.specify？

Cursor、Claude Code 和 GitHub Copilot 默认技能模式用连字符，在 Agent 聊天里调用，不是在终端里输入。Codex 技能模式用 $speckit-specify。文档里的点号写法是参考记法，不要照抄进 Cursor。

Windows 必须先装 WSL 吗？

不必。2026 年的 Spec Kit 在 Windows 上默认使用 PowerShell。初始化时加 --script ps。macOS 和 Linux 默认是 bash，对应 --script sh。

uv 和 pipx 可以各装一次吗？

不要。两套工具会留下两个 specify。PATH 里排在前面的旧版会让 --integration 报错，或出现 No matching release asset found。升级时用当初那一个工具加 --force 或 --upgrade。

git checkout 会切换当前功能吗？

不会。当前功能看 .specify/feature.json，也可以用 SPECIFY_FEATURE_DIRECTORY 覆盖。可选的 git 扩展会建编号分支，但只切换分支并不会改这份状态。

先把命令装对，再让 Agent 改仓库

Spec Kit 的价值不在多一个斜杠，而在把「先规格、再计划、最后改文件」写成仓库里能复查的文件。Windows 用 PowerShell，macOS 和 Linux 用 bash，Cursor 用 cursor-agent 和连字符技能。小功能走短路径，要上线走完整路径，implement 放在隔离节点上。下一步不是再收集提示词，而是用 specify version 确认你面前这个二进制就是你刚装的那一个。

延伸阅读

• 规范驱动开发完全指南：方法论怎么落地 →
• Agent Skills 怎么装、该装哪些 →
• OpenClaw 云端自动化与远程 Mac →