Spec Kit 怎么用:规格驱动开发 9 步上手教程

让编程 Agent 直接「做个看板」,它常常一口气写完、方向却偏了。GitHub 开源的 Spec Kit(MIT,截至 2026-11-07 约 14.8 万星,最新 v1.3.2)把这件事拆成固定步骤:先写规格说明(spec),再定技术方案、拆任务、实现、核对,每一步都落成 Markdown 文件,由你审过再往下走。本文按官方 README 和文档整理安装、9 步流程、老项目接入和 Claude Code / Codex / Cursor 里的调用写法。
Spec Kit 解决的是「先想清楚再写」
直接给 Agent 一句需求,它会自己补全大量没说的假设:用什么框架、数据存哪、谁能改什么。等你看到代码才发现想法不一样,返工成本已经很高。
Spec Kit 的做法是把「做什么、为什么」和「怎么做」分开。规格阶段只写需求和用户故事,不谈技术栈;到计划阶段再交代框架和架构。中间可以插澄清、检查清单、一致性分析几道关口。每一步都是装进 Agent 的一个 Skill,生成的文件放在仓库里,可以 diff、可以评审。
| 对比项 | 直接对话让 Agent 写 | 用 Spec Kit |
|---|---|---|
| 需求在哪 | 散在聊天记录里 | specs/<编号-功能名>/spec.md |
| 技术选型 | Agent 自己猜 | /speckit-plan 时由你给出 |
| 任务拆分 | 一次性写完 | tasks.md 按依赖排序、分阶段 |
| 完工判断 | 看着差不多 | /speckit-converge 对照规格查漏 |
| 项目规则 | 每次重新交代 | .specify/memory/constitution.md 长期生效 |
前置条件
- Linux、macOS 或 Windows;Python 3.11+(PyPI 上
specify-cli1.3.2 标注>=3.11)。 - 包管理器 uv(官方推荐),或 pipx。
- 一个已装好的编程 Agent。集成目录列了 40 多个:GitHub Copilot、Claude Code、Codex CLI、Cursor、Gemini CLI,以及 Qwen Code、Kimi Code、通义灵码、Trae、CodeBuddy 等国内工具。
- Git 可选:只有启用 git 扩展、想要编号功能分支时才需要。
第 1 步:安装 CLI 并初始化项目
在终端里装 CLI,然后按你用的 Agent 选集成 key 初始化:
uv tool install specify-cli
specify version
# 新项目,按 Agent 选 key:copilot / claude / codex / cursor-agent / gemini …
specify init my-project --integration claude
cd my-project
想锁定版本,官方推荐从 GitHub 按发布标签装:uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.3.2(标签要带开头的 v)。在 CI 或 Agent 环境里跑 init,加上 --non-interactive,不然会卡在方向键选择界面。脚本默认按系统选 Bash 或 PowerShell,也能用 --script sh|ps|py 指定。
初始化会生成共享目录 .specify/,外加对应 Agent 的 Skill 文件。官方集成页写的位置:
| Agent | 集成 key | Skill 位置 | 聊天里怎么调用 |
|---|---|---|---|
| Claude Code | claude | .claude/skills/speckit-*/SKILL.md | /speckit-specify |
| Codex CLI | codex | .agents/skills/speckit-*/SKILL.md | $speckit-specify |
| Cursor | cursor-agent | .cursor/skills/speckit-*/SKILL.md | /speckit-specify |
| GitHub Copilot | copilot | 默认 skills 模式 | /speckit-specify |
官方参考文档里常见的 /speckit.specify 是带点的记法,指同一个步骤。你的 Agent 显示哪种写法,就用哪种。
第 2 步:在 Agent 聊天里走 SDD 流程
从这里开始,命令都在 Agent 的聊天框里敲,不是终端。官方要求一次只跑一步,看完结果再进下一步。下面用 Claude Code 的写法,示例取自官方快速上手里的「Taskify」团队看板。
/speckit-constitution Taskify 安全优先:所有用户输入都要校验,代码要有完整文档。
/speckit-specify 做一个团队看板:预置 5 个用户(1 个产品经理、4 个工程师)、3 个示例项目,任务可指派、评论,在 To Do / In Progress / In Review / Done 四列之间拖动。第一期不做登录。
/speckit-clarify 重点澄清任务卡:状态流转、评论权限、谁能被指派。
/speckit-plan 前端用 Vite + 原生 JavaScript,数据存本地 SQLite,提供项目、任务、通知的 REST API。
/speckit-checklist
/speckit-tasks
/speckit-analyze
/speckit-implement
/speckit-converge
每一步做什么、留下什么:
- constitution:项目原则,每个项目只跑一次,写进
.specify/memory/constitution.md,后面每一步都拿它对照。 - specify:只写需求和原因,不写技术栈。默认在
specs/下建001-xxx这样带编号的功能目录,生成spec.md;当前功能记在.specify/feature.json,不看 Git 分支。 - clarify:每次最多问 5 个针对性问题,把回答写回
spec.md,可以多跑几轮。 - plan:这一步才交代技术栈,产出
plan.md,按需还有research.md、data-model.md、contracts/、quickstart.md。 - checklist:官方叫它「需求的单元测试」,检查的是规格本身全不全、有没有歧义。勾
[x]的应该是评审人,不是 Agent。 - tasks:按依赖排序的
tasks.md,分 Setup、Foundational、每个用户故事一段、最后 Polish,能并行的会标出来。 - analyze:只读,交叉检查 spec、plan、tasks 有没有冲突和缺口;有问题回源文件改,再跑一遍。
- implement:按阶段执行任务;开始前会看检查清单,有没勾的项会先问你。
- converge:对照规格查代码,只会往
tasks.md追加任务,不改代码。报告Converged才算完,否则回到 implement 再来。
小功能走短路径:specify → plan → tasks → implement → converge;要上生产的,再把 clarify、checklist、analyze 三道关口加回来。
第 3 步:老项目怎么接入
已有代码的仓库不需要先把整套系统补写成规格。官方建议:
- 先提交或 stash 现有改动,开一个新分支,让生成的文件都能在评审里看到。
- 在仓库根目录跑
specify init --here --force --integration claude。--force会覆盖冲突的托管路径,但不删你的业务代码;跑完先看 diff。 - constitution 只写仓库里已经成立、或团队明确同意的规则,例如「保持公开 API 兼容」「每个数据库迁移都要有回滚方案」,依据是 README、架构决策、贡献指南和 CI 配置。
- 第一个 specify 挑边界清楚的小改动,把不能动的东西写明,比如「订单页加 CSV 导出,保留现有筛选和权限,不改 JSON 接口返回」。
修 bug 和评估点子另有扩展,不用先走 SDD:specify extension add bug 后跑 /speckit-bug-assess → /speckit-bug-fix → /speckit-bug-test,结论只有 verified 才算修好;specify extension add assess 用来判断一个想法该做、该澄清还是该停。
常见坑
- 在终端里敲
/speckit-specify:这些是 Agent 的 Skill,终端里只跑uv和specify这类安装、初始化命令。 - 旧版 CLI:重复执行
uv tool install specify-cli不会升级。官方举例:0.1.6 跑specify init --integration …会报No such option: --integration。用specify self check查新版本、specify self upgrade升级;项目里的文件再跑specify integration upgrade <key>。 - Skill 太多挤上下文(Claude Code):默认每个 Spec Kit Skill 都能被模型自动调用,描述常驻上下文。初始化时加
--integration-options="--no-model-invocation",核心 Skill 就只在你手动输入时触发。 - 以为切 Git 分支就切了功能:当前功能看
.specify/feature.json(或环境变量SPECIFY_FEATURE_DIRECTORY),只git checkout不会变。 - 社区组件直接装:
specify extension search能搜到大量社区扩展,官方写明目录收录不等于审计,装之前先读源码。
完成标准
specify version能输出版本号,项目里有.specify/和你那个 Agent 的speckit-*Skill 目录。.specify/memory/constitution.md写的是真实规则,不是模板占位。specs/001-…/下有spec.md、plan.md、tasks.md,你逐个看过。/speckit-analyze没报冲突,/speckit-converge报告Converged,再开 PR 走正常评审。
想自己写 Skill 或斜杠命令,可以对照站内的 第一个 Agent Skill 怎么写 和 Claude Code 斜杠命令;用 Codex 的话,先按 Codex config.toml 教程 把审批和沙箱设好。
最后
挑一个下周要做的小功能,用 specify init --here 接进现有仓库,只跑短路径 5 步,看 spec.md 和 tasks.md 是否比你平时的聊天需求更清楚,再决定要不要加上 clarify、checklist、analyze 这几道关口。