用 GitHub spec-kit 做 Spec-Driven Development：从需求到代码一条线
上周接了个小项目，照片管理工具，功能不复杂：相册按日期分组，支持拖拽排序，图片瀑布流预览。我估了三天工期，结果一天半就上线了。不是我代码写得快，是压根没怎么写代码------大部分时间在写需求文档。
这听着有点反直觉。写需求文档能比写代码快？
答案是 spec-kit。GitHub 官方出的工具，目前 103k star，本周还在涨。它做的事情很简单：你写需求，AI 把需求变成代码。但跟你直接让 ChatGPT "帮我写个照片管理工具" 不一样，spec-kit 在中间加了一层结构化的流程------需求文档 → 技术方案 → 任务拆解 → 逐个实现。
先装上
bash
# 需要 Python 3.11+ 和 uv
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.2.0
# 初始化项目，选你用的 AI 编码工具
specify init photo-album --integration claude
cd photo-album跑完 specify init 后，项目根目录多了一个 .specify/ 文件夹，里面是模板和脚本。如果你用 Claude Code，它会自动注册一组 /speckit.* 命令。
第一步：写宪法（constitution）
不是开玩笑，spec-kit 管项目原则叫 "constitution"。
bash
/speckit.constitution 代码质量优先：所有函数必须有类型注解，
测试覆盖率不低于 80%。UI 一致性：用 Tailwind CSS，不混写行内样式。
性能：首屏加载控制在 2 秒内。这一步生成了 .specify/constitution.md，后面所有代码生成都会参考这个文件。我一开始没当回事，跳过了这步，结果后面生成的代码风格乱七八糟------有的函数有类型注解，有的没有，Tailwind 和行内样式混着来。回头补上 constitution 之后，重新生成，统一了。
踩坑记录：constitution 不是装饰品。你不写，AI 就自由发挥，出来的东西像五个人写的。
第二步：定义需求（specify）
这步最关键，也是跟 "让 AI 直接写代码" 最大的区别。
markdown
/speckit.specify 一个照片管理应用。功能：
1. 相册列表页，按日期自动分组，支持拖拽调整顺序
2. 相册详情页，照片瀑布流展示，支持点击放大
3. 图片不上传服务器，元数据存本地 SQLite
4. 相册不嵌套，不支持子相册spec-kit 会追问你。"日期分组是按天还是按月？" "拖拽排序持久化吗？" "瀑布流是固定列还是自适应？" 这些问题不是废话------每个都是后面可能出 bug 的地方。
追问结束后，生成了 .specify/prd.md，大概 1500 字的需求文档，包含用户故事和验收标准。我看了一遍，改了两处措辞，加了一条 "图片最大 20MB" 的限制。
第三步：技术方案（plan）
bash
/speckit.plan 用 Vite + vanilla JS，尽量少引第三方库。
图片存本地文件系统，元数据用 better-sqlite3。这步生成了 .specify/plan.md，里面把每个需求映射到了具体的技术选型和文件结构。比如拖拽排序用了 HTML5 Drag and Drop API，没引 sortable.js。瀑布流用 CSS columns 实现，不依赖 Masonry 库。
有意思的地方：plan 文件里每个技术决策都标注了理由。选 CSS columns 而不是 Masonry 的理由写的是 "符合 constitution 中零依赖原则，且对于固定宽度列已足够"。这条追溯链很实用------三个月后你回来看代码，不用猜当时为什么这么选。
第四步：任务拆解（tasks）
bash
/speckit.tasks自动生成了 12 个任务，每个带优先级和依赖关系。前 3 个是基础设施------项目脚手架、数据库 Schema、路由配置。中间 6 个是核心功能------相册 CRUD、图片导入、瀑布流渲染、拖拽排序。最后 3 个是收尾------错误处理、性能优化、测试补全。
任务粒度刚好。不像手写的 JIRA 故事那么粗（"实现相册功能"），也不像某些 AI 拆得太碎（"创建 CSS 文件"）。每个任务大概 30 分钟到 2 小时的工作量。
第五步：执行（implement）
bash
/speckit.implement这步开始生成代码。spec-kit 按任务依赖顺序逐个执行，每完成一个任务提交一次。整个过程大概跑了 40 分钟，生成了 2800 行代码、18 个文件。
跑完之后我做了什么？Review。逐个 diff 看了一遍，改了几处：
- SQLite 的日期字段用的 TEXT 类型存 ISO 格式，我改成了 INTEGER 存时间戳------查询排序快一点
- 拖拽排序的事件监听挂在了每个卡片上，换成了事件委托挂到容器------相册多的时候性能好一些
- 图片加载没做懒加载，我加了 IntersectionObserver
这三处改动共 60 行左右。2800 行里改 60 行，2% 的修改率。
改需求呢？
上线后老板说要加个搜索功能。传统做法是先改 PRD，再改技术方案，再改代码。spec-kit 的做法：
bash
/speckit.specify 追加需求：相册支持按名称搜索，搜索框在列表页顶部。
输入时实时过滤，不走后端，纯前端匹配。跑完后 prd.md 自动更新了，多了一条用户故事。再跑 /speckit.plan 和 /speckit.tasks，增量生成了 2 个新任务。再 /speckit.implement，5 分钟搞定。
这就是 SDD（Spec-Driven Development）的核心思路------需求文档是主角，代码是副产品。改需求不用翻代码找影响范围，直接改文档，让 AI 重新生成。
适合什么场景
用了两周，我的判断：
适合的：
- 新项目从零开始。spec-kit 的 constitution → specify → plan → tasks → implement 流程很顺，适合 0 到 1
- 功能明确的工具类项目。需求能用几段话说清楚的那种
- 快速原型验证。写完需求文档到看见能跑的 demo，通常一两小时
不太适合的：
- 已有大量代码的老项目。spec-kit 目前没有 "从已有代码反向生成 spec" 的能力
- 需要复杂业务逻辑的系统。银行交易、医疗系统这种，需求文档本身就要几十页，spec-kit 的追问机制扛不住
- 对生成代码质量有极致要求的场景。生成的代码能跑，但不一定是最优解，Review 和手动调优还是必要的
跟 "直接让 AI 写代码" 到底差在哪
我做了个对比。同样的照片管理需求，直接用 Claude Code 写：
帮我做一个照片管理工具，相册按日期分组，支持拖拽，瀑布流展示20 分钟出了结果，能跑。但：
- 没有类型注解
- 引了 3 个我不需要的库
- 拖拽排序有 bug，空相册拖到最后位置会报错
- 没有测试
用 spec-kit 写：40 分钟出结果，也能跑。区别是：
- 有类型注解（constitution 要求的）
- 零第三方库（plan 里决定的）
- 拖拽排序没 bug（因为 specify 阶段追问了边界情况）
- 生成了 12 个测试用例
多花的 20 分钟在写需求文档和回答追问上。换来的是更少的 bug 和更清晰的架构。项目越大，这个差距越明显。
几个实用技巧
1. constitution 越具体越好
别写 "代码质量好"，写 "函数不超过 30 行，必须有 JSDoc 注释"。
2. specify 阶段主动写反例
"不支持子相册" "图片不上传服务器" 这种否定式需求很重要。你不说不支持，AI 可能就给你做了。
3. plan 阶段指定约束，别指定实现
"用 CSS 实现瀑布流" 比 "用 CSS columns 的 column-count 属性实现瀑布流" 好。前者给 AI 选择空间，后者锁死了方案。
4. implement 后一定要 Review
spec-kit 不是银弹。生成的代码有时会有性能问题，有时会忽略边界情况。把它当成一个写代码很快但经验不足的初级开发者------产出靠谱但需要 Senior 过一遍。
项目地址
- GitHub: github.com/github/spec...
- 文档: 项目 README 写得很清楚，
specify init之后跟着/speckit.specify一路走就行 - 支持的 AI 工具: Claude Code、GitHub Copilot、Gemini CLI、Codebuddy、Pi