@toc
一、先说痛点：AI 写代码翻车，八成翻在需求传递上
后端同学大概率经历过的场景。
你跟 AI 说："帮我加个退款接口。"
它唰唰唰生成一整套 controller、service、异常处理，编译能过、测试能过、跑起来也没毛病。上线第二天运营来找你：用户把已经发货的订单也退了。
代码没 bug。坑出在那句 prompt 里压根没提"发货状态"这四个字。
AI 没有失败在写代码上，它失败在猜你心思上。写得越快，方向跑偏得越快，返工的时候你甚至说不清当初想要什么。这在传统软件工程里有名字，叫需求问题；到了 AI 编程时代，它被放大了十倍，因为 AI 会一丝不苟地实现你含糊的意图，包括错误的部分。
GitHub 官方的 Spec Kit 就是冲着这个问题来的。
二、Spec Kit 是什么
先上项目卡片：
| 项目 | 信息 |
|---|---|
| 仓库 | github/spec-kit |
| 出品方 | GitHub 官方 |
| 协议 | MIT |
| 热度 | 14.8 万+ Star，周增 4000+（2026-11 数据） |
| 最新版本 | v1.3.1 |
| 定位 | 规格驱动开发（Spec-Driven Development, SDD）工具包 |
它的核心理念一句话：先定义"做什么、为什么"，再让 AI 决定"怎么做"。
传统开发里 spec 是写完就扔的脚手架。Spec Kit 把它变成一条可执行的产物链：
constitution.md → spec.md → plan.md → tasks.md → 代码 → converge 对账每个阶段产出一个 Markdown 文件，喂给下一阶段的 agent。spec 不再是文档，是事实来源。
它由两部分组成：
specifyCLI（Python 写的）：负责项目脚手架、集成管理；- 一组斜杠命令 ：装进你的 AI 编码工具里，像
/speckit-specify这样一条条跑。
支持的 agent 相当全：Claude Code、GitHub Copilot、Codex、Gemini CLI、Cursor、Cline、opencode、Qwen Code、Kiro CLI、Zed 等 20+，还有 generic 兜底模式，自己接任何工具都行。
三、十分钟上手：安装与初始化
要求：Python 3.11+、uv、任意一个支持的编码 agent。
bash
# 安装 CLI
uv tool install specify-cli
# 初始化项目（以 Claude Code 集成为例）
specify init my-project --integration claude
# 已有项目在当前目录初始化
specify init . --integration claude
# 检查环境
specify check初始化完成后，项目里多出一个 .specify/ 目录，AI 工具那边多出一组 skill。目录长这样：
text
my-project/
├── .specify/
│ ├── memory/
│ │ └── constitution.md # 项目"宪法"
│ ├── templates/ # spec/plan/tasks 模板
│ └── scripts/ # 辅助脚本（sh/ps/py 三种）
├── .claude/skills/ # 斜杠命令对应的 skill（按集成的工具不同）
└── specs/ # 每个功能一个目录，产出物都在这一个小提醒：官方安装时会提示把 .claude/ 之类的 agent 目录加进 .gitignore，有些工具会把本地私密配置写进去，别连着密钥一起提交了。
四、完整工作流：六步走一遍
命令一次敲一条，看完产物再敲下一条，这是官方 README 反复强调的节奏。下面用一个 FastAPI 小服务（订单查询接口）当例子，看看每一步实际产出什么。
4.1 /speckit-constitution：先立宪法
text
/speckit-constitution
项目原则：1) 所有接口必须有参数校验和明确错误码；2) 数据层用 SQLite WAL；
3) 每个功能先写测试；4) 代码里不允许出现真实生产数据。agent 会把这几条写进 .specify/memory/constitution.md，以后每一步都会回读它。这一步全项目只做一次，相当于给 AI 划红线：之后不管哪个 agent 干活，都不能违背这些原则。
为什么这步值钱：多 agent 并行的人都有体会，同一个规范口头说三遍，三个 agent 能给你三种理解。落到文件里，就是一份人人遵守的硬约束。
4.2 /speckit-specify：只谈业务，不谈技术
text
/speckit-specify
做一个订单查询功能：按订单号查详情，支持分页查列表；
已取消订单（30 天前）不出现在列表里，但单查还能查到，并标记"已过期"。产出 specs/001-order-query/spec.md，里面是结构化的用户故事、编号的功能需求（FR-1、FR-2......）和边界情况清单。注意这个阶段不要写技术栈，一旦过早进入"怎么实现"，伪约束会污染规格。
spec 里最有价值的部分往往是边界情况。拿我这个例子说，agent 会主动列出：订单号不存在返回什么？分页翻到没有数据的页返回什么？"30 天前"按创建时间算还是取消时间算？
4.3 /speckit-clarify：逼 AI 把模糊处问出来（可选但强烈推荐）
text
/speckit-clarify这一步 agent 会反问你，一次最多五个问题，把 spec 里模糊的点问成明确结论，答案写回 spec。退款限不限发货状态、任务 ID 删了能不能复用，这些"没人想拍板的决策"全在这一步摊牌。
写代码前把话说死，比写完代码再吵便宜得多。
4.4 /speckit-plan：这时才谈技术
text
/speckit-plan
用 FastAPI + SQLite(WAL)，单文件部署，接口返回统一结构 {code, msg, data}。产出 plan.md，外加数据模型（data-model.md）、接口契约（contracts/）、技术调研记录。技术决策在这一步写实，且会回头对照宪法做合规检查。
4.5 /speckit-tasks：拆成带依赖的任务清单
产出 tasks.md：任务按用户故事分组、按依赖排序、每个任务带独立验收标准。测试任务会排在对应实现任务前面。
对做过多 agent 并行开发的人来说，这份文件就是最规范的"拆任务产物"，可以直接按任务分派给不同 agent。
4.6 /speckit-implement：照单干活
agent 按任务顺序实现，每完成一个勾一个。真跑过的公开实测（一个命令行 todo 应用）里，implement 产出 109 行代码 + 14 个测试，全绿。
4.7 /speckit-converge：拿代码对账，这是全场最有价值的一步
上面的 todo 实测里有个细节值得单独说：implement 结束，14 个测试全过，看起来完美。结果一跑 converge：
- 它拿代码逐条对照 spec.md / plan.md / tasks.md；
- 抓出一个测试完全没覆盖的坑：spec 要求"存档文件损坏时给出清晰错误提示且不能被覆盖"，实际代码遇到损坏文件直接抛 Python 异常崩掉；
- 把差距追加 成新任务（append-only，不改已有代码），再跑一轮 implement，直到报告
Converged。
人 review 代码，看的是代码本身；converge 对的是需求原文。两条视线交叉，漏网的才少。另一个带真实业务规则的预约系统实测里，converge 和 analyze 抓到的都是"测试没问到的缺口"，恰好是平时最容易带病上线的那类问题。
全部走完后，一个功能的产物长这样：
text
specs/001-order-query/
├── spec.md # 需求：用户故事 + FR + 边界情况
├── plan.md # 技术方案
├── data-model.md # 数据模型
├── contracts/ # 接口契约
├── quickstart.md # 本地跑通指引
└── tasks.md # 任务清单（含 converge 追加的任务）五、我的判断：价值在两个环节，不在模板
用下来我的结论是，Spec Kit 的卖点容易被理解偏。它不是"又一套文档模板"，模板谁都能抄，抄完该漏还是漏。真正值钱的是：
- clarify 的追问机制：它逼着你在写代码之前，把那些"所有人都以为别人会考虑"的决策摆上台面。有价值的不是第一版 spec，是它被追问之后留下来的那一版。
- converge 的收敛循环：传统"AI 写完我人肉 review"缺的那半环。append-only 的设计也很克制，发现问题只追加任务不动代码，避免了"AI 为了过检查偷偷改代码"的新坑。
同时也要泼盆冷水：spec 错了，代码会忠实地错下去。converge 只能告诉你"代码完美符合这份 spec"，不能告诉你 spec 本身对不对。这件事，永远得人来。
六、对照我自己的工作流：哪些作业值得抄
我自己日常是重度多 agent 用户，习惯的打法是先搭框架，再把活拆成文件丢给多个 agent 并行跑。拿 Spec Kit 的六步一对照，结论有点扎心：
| 环节 | Spec Kit | 我的流程 |
|---|---|---|
| 项目规范 | constitution.md 书面版 | 全在脑子里和记忆文件里 |
| 需求 | spec.md + clarify 追问 | 口头描述，经常一句"做个 XX" |
| 拆任务 | tasks.md 带依赖 + 验收标准 | 拆文件靠经验，验收标准含糊 |
| 验收 | converge 代码对账 | agent 交付什么我看什么 |
| 并行 | 任务天然可分派 | 我的核心优势，这块我不换 |
也就是说，我只手搓了它的中间一段：specify 和 tasks 干了，constitution 没有书面版，converge 压根不存在。并行跑得越快，收尾那个没验收标准的口子漏得越多。
所以我打算分两步抄作业，不照搬全套：
- 先给项目补一份自己的 constitution：脱敏规则、分支规范、测试要求，几条就够；
- 拆任务前，把口头描述换成带验收标准的 spec 段落，重点给并行的任务块补上"什么算完成"。
七、什么时候别用它
一个跑过完整流程的实测作者的结论我非常认同：用消除歧义所需的最小严格度。每个功能产出十来个文档文件，仪式感是有成本的。我的划分：
| 场景 | 建议 |
|---|---|
| 探索性脚本、一次性数据处理 | 别用，直接让 AI 写 |
| 一小时内能修完的小改动 | 别用，口头说清楚就行 |
| 多 agent 并行的功能块、要上线的业务逻辑 | 值得用，重点用 specify + tasks + converge 三步 |
| 从 0 到 1 的新项目 | 全流程走一遍，宪法一次管到底 |
八、命令速查表
| 命令 | 作用 | 必须吗 |
|---|---|---|
/speckit-constitution |
立项目原则，全项目一次 | 是（一次） |
/speckit-specify |
需求 → spec.md，只谈 what/why | 是 |
/speckit-clarify |
反问澄清模糊点，写回 spec | 强烈推荐 |
/speckit-plan |
技术方案 → plan.md + 契约 | 是 |
/speckit-tasks |
拆任务，带依赖和验收 | 是 |
/speckit-analyze |
只读检查 spec/plan/tasks 一致性 | 可选（质量门） |
/speckit-implement |
按任务实现 | 是 |
/speckit-converge |
代码对账 spec，追加差距任务 | 是（循环到 Converged） |
九、常见问题
Q：必须用 GitHub Copilot 吗？ 不用。它对 agent 是中立的，Claude Code、Codex、Cursor、opencode 等 20+ 都行
Q：和传统 PRD 什么关系？ PRD 是写给人看的参考，SDD 的 spec 是给 agent 执行的事实来源，带编号、带验收标准、可 diff 可追溯。
Q：spec 要不要一直维护？ 要。代码改了 spec 不改，converge 会一直报差距。把它当测试用例看待：改需求先改 spec。
十、写在结尾
它至少说明一件事：大家用 AI 写代码的痛点，已经从"写不出来"转移到了"写出来的不是我想要的"。
Spec Kit 干的活，说到底是把那句老话往前挪了一步：**garbage in, garbage out。含糊的需求进，忠实的垃圾代码出。**它管不了你要什么，但能管住 AI 交付的东西和你说的一致。
参考链接：
- Spec Kit 仓库：github.com/github/spec...
觉得有用的话点个赞 + 收藏，评论区聊聊你的 AI 编码工作流。