上个月我在用 Claude Code 开发一个新功能需求说得很清楚「给用户列表页加一个按注册时间排序的功能」。AI 给出的代码看起来很完整——接口、Service 层、前端组件都有。但跑起来发现排序逻辑用的是前端分页后的本地排序不是数据库层面的排序。数据一多就废了。改完这个又发现它用的是创建时间字段而不是注册时间。我花了半小时 PromptAI 花了半小时「改」最后代码改了七八版还是有问题。这就是 vibe coding 的典型死法——AI 写得很快但方向从一开始就偏了速度越快越难收。GitHub 在今年 5 月开源了一个叫 Spec Kit 的工具专门解决这个问题。发布不到一个月它已经拿到了11 万 Star、9,700 个 Fork是今年 GitHub 上增长最快的 AI 工具类项目之一。这篇文章的核心结论先放在这里规范文件spec.md是 AI 编码里最被低估的基础设施。写好它你跟 AI 的对话质量会有质的提升不是因为 Prompt 技巧变好了而是因为 AI 终于知道它要做的是什么。为什么 Vibe Coding 的天花板这么低先说清楚问题再说解决方案。vibe coding 这个词是 Andrej Karpathy 提出的原意是「顺着感觉写代码让 AI 处理细节」。在原型验证阶段这个方式非常有效——你描述个大概AI 给你一个能跑起来的架子5 分钟内看到效果。但进入真正的功能开发之后这个模式会遇到一个内在矛盾AI Agent 不是搜索引擎它是「字面意思执行者」。你说「加一个排序功能」它就加排序功能。它不知道你的数据量有多大不知道你的分页逻辑在哪一层不知道「注册时间」和「创建时间」在你的 schema 里是不是同一个字段。它把所有这些模糊的空间用它认为「合理」的猜测填满了。这就是 GitHub 官方文章里说的那句话it looks right, but doesnt quite work——看起来对但跑起来不对。更深的问题是需求漂移context drift。你在一个长对话里反复修改需求AI 的「记忆」会逐渐偏离最初的意图。第 10 轮修改的代码和第 1 轮的需求之间可能已经没有直接的对应关系了。这不是 AI 的智力问题是信息结构的问题。vibe coding 本质上是把「需求」藏在了对话历史里分散在十几条消息的来回里。AI 每次生成代码都需要从这些碎片里重建上下文每次重建都可能丢失细节。Spec Kit 的解法是把需求从对话里拿出来放到一个结构化的文件里。这个文件就是 spec.md它是整个开发流程的单一真相源。AI 每次做任何决策都从这里取信息而不是从对话历史里猜。图左边是 vibe coding 的信息结构——需求散落在对话里AI 每次都在猜右边是 SDD 的信息结构——spec.md 是唯一真相源AI 从这里取信息Spec Kit 的核心设计七步工作流Spec Kit 的安装很简单核心是一套七步工作流每一步生成一个文件这些文件共同构成一个功能的「完整规范体系」。在看具体命令之前先理解这个设计哲学规范先于实现文件先于代码。传统开发是先写代码遇到问题再补文档。Spec Kit 是先写规范让规范驱动代码生成。这个顺序的改变意义远大于工具本身的功能。七步工作流全景步骤命令生成文件核心作用1/speckit.constitution.specify/memory/constitution.md项目治理原则所有后续决策的底线2/speckit.specifyspecs/[FEATURE]/spec.md用户故事和功能需求only「what」和「why」3/speckit.planspecs/[FEATURE]/plan.md技术架构和技术栈选型4/speckit.clarify—解决歧义提前暴露假设5/speckit.tasksspecs/[FEATURE]/tasks.md带依赖关系的任务清单6/speckit.analyze—跨文件一致性验证7/speckit.implement实际代码系统性执行所有任务这七步里最容易被跳过的是第 4 步clarify和第 6 步analyze。跳过这两步的代价往往在第 7 步才暴露出来——任务跑到一半发现两个模块的接口不兼容或者某个边界情况根本没考虑进去。有实践者在完整走完一个 Azure 微服务项目后报告在 analyze 阶段自动发现了 9 个潜在问题包括「缺失 FluentValidation 验证器」和「DI 注册顺序错误」——这两个如果等到 implement 阶段才发现代价是完全不同的。最终生成的目录结构是这样的specs/[FEATURE]/ ├── spec.md # 用户故事和功能需求 ├── plan.md # 技术架构和决策 ├── tasks.md # 带依赖关系的工作分解 ├──>图Spec Kit 七步工作流每一步都有明确的输入和输出AI 在整个过程中是执行者而非决策者一张对比图vibe coding vs SDD 的真实差异光说原理不够直观我来画一张更具体的对比。假设你要开发「用户注册邮件验证」功能。vibe coding 路径第 1 轮 Prompt「帮我实现用户注册的邮件验证功能」 → AI 给了一个完整的实现用了某个邮件库有验证码逻辑第 2 轮「验证码的有效期改成 10 分钟」 → AI 改了但顺便把验证码长度也改了你没说保持不变第 3 轮「验证链接要包含用户 ID 吗」 → AI 说「可以」然后改了实现但新的 URL 格式和你的路由配置冲突了第 4 轮「路由报 404」 → ...SDD 路径Spec Kitspec.md 里明确写了验证方式链接不是验证码有效期10 分钟URL 格式/verify?token{jwt_token}token 包含 user_id不暴露在 URL 里依赖库已有的spring-boot-starter-mail不引入新依赖plan.md 里明确写了用 Redis 存储 tokenkey 格式email:verify:{token}TTL 10 分钟验证接口GET /verify的参数和响应格式tasks.md 里明确写了Task 1Redis 存储逻辑无前置依赖Task 2邮件发送服务依赖 Task 1Task 3验证接口依赖 Task 1Task 4前端「已发送验证邮件」提示页无后端依赖AI 执行/speckit.implement的时候它知道每一个 task 要做什么、不能做什么、依赖什么。33 个 task逐一 ✅。这不是说 SDD 没有返工而是返工发生在「写文档」阶段而不是「跑测试」阶段——在 spec 里改一行字的代价远低于在代码里 debug 一个小时。图两种模式下的返工时机对比——SDD 把问题暴露在「写规范」阶段vibe coding 把问题留到「跑代码」阶段这套方法的边界在哪里Spec Kit 不是银弹有几个场景它不适合1. 5 分钟的快速原型如果你只是想看看「这个 API 能不能用」「这个 UI 大概长什么样」vibe coding 更快。Spec Kit 的七步工作流是有成本的这个成本在原型验证阶段不划算。2. 需求高度不确定的探索期如果你连「要做什么」都还没想清楚写 spec 会很痛苦——你不知道要往里填什么或者每天都在改。这个阶段 vibe coding 反而是合理的因为你在用代码来探索需求。3. 独立开发者的个人小项目五步规范流程对一个人做的小工具来说太重了。不过即使不用完整流程constitution.md 这个单一文件就值得写——它相当于你给 AI 的全局配置比每次 Prompt 里重复说约束高效得多。Spec Kit 真正发挥价值的场景是多人协作项目AI 需要和不同成员的约定保持一致功能复杂度高涉及多个模块和接口契约有遗留系统需要在已有代码约定下做新开发对交付质量有明确验收标准的功能用 GitHub 自己的分类绿地新项目greenfield、已有系统加功能N1、遗留系统改造——Spec Kit 对这三类都有具体的预设支持。目前它已经有105 个社区扩展、22 个预设包括专门针对 Spring Boot 项目、Go 微服务、前端组件库的特化版本。装完基础工具后用specify extension list可以看到完整目录。常见问题Q写 spec.md 很花时间我这种快节奏团队用得起吗这个问题的隐含假设是「写文档 额外成本」。换个角度你现在花在解释需求、修 AI 的错、合并冲突上的时间有多少spec.md 把这些成本前置了。按 Peter Saktor 的实测经验完整走完 Spec Kit 流程的项目33 个任务全部正确完成0 编译错误——而不走规范流程时同等复杂度的功能通常需要多轮返工。QSpec Kit 支持中文写 spec 吗完全支持。constitution.md 和 spec.md 都可以用中文写AI 理解没有问题。甚至更推荐中文写——因为你的团队用中文思考需求写规范的时候用中文更不容易出现翻译层的信息损耗。Q我现在用 Cursor需要换工具吗不需要。Spec Kit 支持 Cursor 的.cursorrules模式specify init my-project --integration cursor就行。它的设计本来就是工具无关的规范文件spec.md/plan.md/tasks.md是纯 Markdown任何 AI 工具都能读。QSpec Kit 本身会过时吗这是个好问题。AGENTS.md 和 CLAUDE.md 这类「AI 配置文件」的生态已经在快速标准化Linux Foundation 旗下已有 60 工具支持 AGENTS.md 这个格式。Spec Kit 的 constitution.md 是这一趋势的进化版——如果说 AGENTS.md 是给 AI 的使用说明书constitution.md 是给 AI 的工程契约。方向是对的标准化程度只会越来越高。Q规范文件太详细会不会限制 AI 发挥这里有个认知误区我们不是想让 AI「发挥创意」我们想让 AI「准确执行意图」。规范文件限制的不是 AI 的能力是 AI 的猜测空间——让它少猜多做。生产代码里 AI 的「创意发挥」大多数情况下是麻烦的来源而不是价值的来源。总结说到底Spec Kit 解决的不是「怎么跟 AI 说话」的问题是「把什么东西告诉 AI」的问题。Prompt 再好也只是在优化「信息传递的效率」spec.md 改变的是「你给 AI 的信息结构」——这两件事的量级不在同一个层面。我在几个项目里推广下来的感受是前三次用 Spec Kit 会觉得「这也太繁琐了」第四次开始就不想回去了因为你会清楚地感受到少返工有多爽。下一篇打算拆解 constitution.md 的完整写法给出针对不同技术栈的中文模板感兴趣的关注一下。如果你身边有团队正在规模化推广 AI 编码这篇可以直接甩给他们比重新解释一遍省事。