GitHub官方129K星的spec-kit上手：3步让AI Agent先写规格再写代码，告别反复返工

用 AI 编程最烦的是什么？需求没说清楚，代码写出来全不对，然后来回返工。GitHub 官方开源的 spec-kit（规格开发套件）就是来解决这个问题的——它让 AI Agent 先写”规格说明书”，再写代码。今天它在 GitHub Trending 上涨了 901 星，累计 12.9 万星。

规格驱动开发是什么

传统开发是”先写代码，规格只是草稿纸”；spec-kit 把顺序反过来：规格变成可执行的东西，直接生成实现。流程是：定原则 → 写需求 → 做技术方案 → 拆任务 → 执行实现 → 验证收敛。

这套流程天然适合 AI 编程：Agent 上下文有限，需求越清晰，产出越靠谱。规格先行的最大好处，是让 AI 在动手前就想清楚”做什么、为什么”，而不是猜。

前置条件

– Python 3.11+、Git；

– 一个 AI 编码 Agent（Claude Code、GitHub Copilot、Codex 等，支持 30+ 种）；

– 包管理工具 uv（推荐）。

第 1 步：安装 specify CLI

uv tool install specify-cli

安装完成后检查版本：

specify --version

如果看到版本号，说明装好了。

第 2 步：初始化项目

specify init my-photo-album --integration copilot
cd my-photo-album

这条命令会为你的项目生成规格驱动的目录结构，并把 AI Agent 的斜杠命令装好。

第 3 步：用四条命令走完整个流程

在项目目录里启动你的 AI 编码 Agent，依次执行：

① 定原则（项目宪法）

/speckit.constitution 制定原则：注重代码质量、测试标准、性能要求

② 写需求（只讲做什么，不讲技术栈）

/speckit.specify 做一个照片管理应用：按日期分组相册，支持拖拽排序，图片不联网上传

③ 技术方案（这时候才谈技术选型）

/speckit.plan 使用 Vite + 原生 HTML/CSS/JS，元数据存本地 SQLite

④ 拆任务并执行

/speckit.tasks
/speckit.implement

Agent 会生成任务清单并逐项实现。如果发现代码和规格对不上，还可以跑：

/speckit.converge

它会对照规格/计划/任务检查代码库，把遗漏的工作追加成新任务，实现”闭环收敛”。

成功验证

– 项目目录里出现 `specs/` 文件夹，里面有规格文档；

– 代码实现与规格逐条对应；

– Agent 输出的任务列表全部完成。

常见失败与处理

| 现象 | 原因 | 解决 |

|——|——|——|

| `specify` 命令找不到 | uv 的 bin 目录没进 PATH | 重新登录终端或 `source ~/.bashrc` |

| 斜杠命令不生效 | Agent 没在项目目录启动 | 必须 `cd` 到初始化后的目录再启动 Agent |

| Copilot 不识别命令 | 集成方式不对 | 用 `specify integration list` 查看可用集成，换 `–integration` 重跑 |

| 生成代码跑偏 | 规格写得不够细 | 先跑 `/speckit.clarify` 补细节，再 `/speckit.plan` |

什么时候值得用

– 新项目从 0 到 1：规格先行，产出可控；

– 老项目加功能：用 brownfield 模式渐进增强，避免 Agent 乱改架构；

– 团队协作：规格文档就是评审材料，人机都能看懂。

一个真实场景的完整流程

举个具体例子：你想做一个”照片整理工具”。按 spec-kit 的标准流程，先跑 `/speckit.constitution` 定下”离线优先、不依赖外部服务”等原则；再跑 `/speckit.specify` 说清楚”按日期分组相册、支持拖拽排序、照片不联网”；然后 `/speckit.plan` 里才指定 Vite + SQLite；最后 `/speckit.tasks` 拆出”建数据库表、写相册页、实现拖拽”等任务，`/speckit.implement` 逐项实现。整个过程中，AI 每次动手前都有明确依据，不会自由发挥。

对团队来说，这套流程还有一个隐藏收益：规格文档本身就是评审材料。产品、测试、AI 看到的是同一份”需求”，沟通成本大幅下降，返工自然减少。这也是 spec-kit 从 GitHub 官方出来的底气——它把大厂内部的”先想清楚再动手”方法论，做成了人人可用的开源工具。

一句话：AI 编程的瓶颈不在代码，在需求表达。spec-kit 把”说清楚需求”变成了标准流程，值得每个重度使用 AI 编程的人试一次。

— END —
LC 智趣厅 · 科技与生活的交点
ihygg.cn