教程2026-11-07 · 智涌AI

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

Spec Kit 规格驱动开发教程头图:左侧标题与 9 步、40+ Agent 集成、MIT 三个数字卡,右侧流程图依次为 specify 写规格、plan 定方案、tasks 拆任务、converge 查漏

让编程 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 长期生效

前置条件

第 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集成 keySkill 位置聊天里怎么调用
Claude Codeclaude.claude/skills/speckit-*/SKILL.md/speckit-specify
Codex CLIcodex.agents/skills/speckit-*/SKILL.md$speckit-specify
Cursorcursor-agent.cursor/skills/speckit-*/SKILL.md/speckit-specify
GitHub Copilotcopilot默认 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

每一步做什么、留下什么:

小功能走短路径:specify → plan → tasks → implement → converge;要上生产的,再把 clarify、checklist、analyze 三道关口加回来。

第 3 步:老项目怎么接入

已有代码的仓库不需要先把整套系统补写成规格。官方建议:

  1. 先提交或 stash 现有改动,开一个新分支,让生成的文件都能在评审里看到。
  2. 在仓库根目录跑 specify init --here --force --integration claude。--force 会覆盖冲突的托管路径,但不删你的业务代码;跑完先看 diff。
  3. constitution 只写仓库里已经成立、或团队明确同意的规则,例如「保持公开 API 兼容」「每个数据库迁移都要有回滚方案」,依据是 README、架构决策、贡献指南和 CI 配置。
  4. 第一个 specify 挑边界清楚的小改动,把不能动的东西写明,比如「订单页加 CSV 导出,保留现有筛选和权限,不改 JSON 接口返回」。

修 bug 和评估点子另有扩展,不用先走 SDD:specify extension add bug 后跑 /speckit-bug-assess → /speckit-bug-fix → /speckit-bug-test,结论只有 verified 才算修好;specify extension add assess 用来判断一个想法该做、该澄清还是该停。

常见坑

完成标准

想自己写 Skill 或斜杠命令,可以对照站内的 第一个 Agent Skill 怎么写 和 Claude Code 斜杠命令;用 Codex 的话,先按 Codex config.toml 教程 把审批和沙箱设好。

最后

挑一个下周要做的小功能,用 specify init --here 接进现有仓库,只跑短路径 5 步,看 spec.md 和 tasks.md 是否比你平时的聊天需求更清楚,再决定要不要加上 clarify、checklist、analyze 这几道关口。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。