1. Vibe-coding的诱惑与失控为什么你需要Spec-kit先说个真实的场景。我接触Vibe-coding最早是从一个side project开始的当时的需求很简单做一个内部用的数据看板把几个业务表的指标汇总成图表。我打开AI编程工具用自然语言描述了页面布局、图表类型、刷新频率AI大概花了二十分钟就把整个项目的骨架推了出来前后端接口、图表组件、样式文件一应俱全。那一刻的感觉确实很爽就像有人替你写完了作业你只需要验收。但这种爽感持续了大概两天。第三天需求变了客户要求加一个新的筛选维度并且要把某个图表的聚合逻辑从按天改成按小时。我打开那个由AI生成的代码仓库试图找到负责聚合的那段逻辑结果发现整个项目里散落着六七个版本的相似函数有的写死在某一个组件内部有的是一个通用工具函数有的是在接口层直接处理。我根本不敢直接改因为根本不知道哪个在真正生效。这就是Vibe-coding最典型的困境。它把写代码这个动作的成本压到了极低但把理解代码、维护代码、修改代码的成本推到了一个离谱的高度。你用自然语言描述了一个感觉AI给你生成了一大堆实现但你和AI之间从来没有一个关于到底要做什么的精确协议。感觉对上了代码就对了感觉没对上你就得在AI生成的一大堆代码里猜谜。于是我开始寻找一种方法让Vibe-coding不只是让AI写代码而是让AI按规格写代码。这就是Spec-kit进入我视野的原因。Spec-kit这个工具的出现本质上是在解决Vibe-coding流程里最要命的一个问题需求从模糊到精确的沉淀问题。它要求你在让AI动手之前先写一份规格说明也就是spec。你不是直接告诉AI给我做一个看板页面而是先定义清楚这个页面有哪些模块、每个模块包含哪些指标、指标的口径从哪里来、刷新的频率是多少、展示的顺序是什么、异常情况下怎么兜底。把这些东西全部落到一份结构化的文档里再让AI基于这份文档去生成代码。用一句话概括Spec-kit的核心思想用规格的确定性约束AI生成的不确定性。它做的最重要的一件事是把人和AI之间的关系从一个松散的混沌状态变成了一个工程化的协作流程。人负责定义规格和验收AI负责生成实现。而Vibe-coding原本的灵感体验也并没有丢失——你依然可以用自然语言去描述需求只不过这些描述变得更结构化、更精确了。相当于你从一个约等于的表达方式升级到了严格等于的工程语言。这篇文章里我会从Vibe-coding的痛点讲起然后把Spec-kit的完整使用流程拆开揉碎结合我实际跑过的两个项目一个数据看板一个内部审批小应用把从写第一份spec到用AI生成代码再到迭代维护的完整链路记录下来。如果你想用Vibe-coding做正经项目而不是只做一个demo这篇文章应该能帮你少踩不少坑。2. Spec-kit的设计逻辑为什么先写规格再写代码能救Vibe-coding2.1 一份好spec到底长什么样我在第一次接触Spec-kit时最大的困惑就是spec这个东西和PRD、技术方案、接口文档到底有什么区别如果只是把PRD丢给AI那为什么还需要Spec-kit后来我用了一个类比才彻底想明白。Vibe-coding就像你请了一个极其聪明、但极其缺乏常识的实习生。你跟他说帮我把桌子收拾一下他会真的去收拾但可能把你的咖啡杯扔进垃圾桶因为在他的理解里收拾意味着清空桌面。你需要的不是反复纠正他每一次的误操作而是给他一本非常详细的《办公室整理手册》什么东西放在哪个位置、哪些东西属于保留品、哪些属于垃圾、桌面的最终状态应该符合什么标准。Spec-kit提供的正是这样一本手册。它定义了一套spec的结构让机器能够理解和解析你的需求描述然后通过结构化的方式把这条需求链完整地透传给AI。我在实际使用中一份合格spec通常包含这么几个层次目标层这个功能要解决什么问题。不是描述具体怎么实现而是描述最终用户的使用场景和预期结果。比如运营人员每天上班第一件事是查看昨日核心指标如果指标异常能在5分钟内定位到异常原因。范围层哪些功能属于本次开发的边界哪些明确不做。比如本次只做看板页面的前端展示不涉及告警推送。逻辑层核心业务逻辑的定义。比如指标的计算口径、筛选条件的交互逻辑、权限的判断规则。这是spec里最重要的部分也是AI最容易在代码里埋雷的部分。界面层页面布局、交互反馈、状态变化。不用太详细到像素级别但要描述清楚每种状态下的界面表现。验收层定义怎么样才算做完。验收标准要可验证、可测量。比如当筛选条件选择过去7天时图表数据源请求参数中的start_time和end_time分别对应7天前的零点与当前时间。把这几层写清楚你手里就有一份AI可以遵循的规格说明书了。Spec-kit会解析这份文档把它转换成AI更容易理解和遵循的指令。2.2 Spec-kit的流转机制从spec到代码的完整链路了解了spec的结构之后有一个很关键的问题Spec-kit是怎么把一份规格说明变成实际代码的它和直接在对话窗口里写prompt的区别在哪里我理解下来区别主要在三个环节。环节一规格的版本化沉淀。在传统的Vibe-coding里你的需求藏在对话记录里。昨天你说了A模块要做X今天你又说了A模块要做YAI会把这两段对话放在整个上下文中理解最后很可能生成一个既有X又有Y的混合逻辑。而Spec-kit让spec成为独立于对话的版本化文件。你改的不是对话你改的是这份规格文件本身。每次迭代你都能清晰地看到规格版本的演变AI的上下文也不会被历史对话的噪声污染。环节二上下文管理。大语言模型是窗口式的它的上下文窗口有限当对话越来越长它就越容易遗忘早期的需求细节。Spec-kit把spec作为结构化的上下文输入让AI在每轮生成时都聚焦在当前的规格内容上而不是靠记得我们前天聊过什么来工作。这在项目一变大之后极其重要——我那个数据看板项目大概有三十多个组件文件如果不依赖specAI根本不知道你当前要改的是哪一个组件的逻辑。环节三验收标准可执行化。你在spec里写的验收标准不只是给人看的。Spec-kit可以配合自动化测试、lint规则等工具把验收标准转换成可执行的检查项。代码生成之后不是靠你肉眼去检查而是靠工具去自动验证。这一步把AI写的代码能不能用从一种主观感受变成了客观质量门禁。这三个环节解决了Vibe-coding体验里最让人胃疼的问题对话即遗忘感觉即偏差验收靠猜。3. 从0到1实操用Spec-kit跑通一个数据看板项目3.1 项目初始化spec驱动的起点我用一个具体案例来演示完整流程。假设我们要做一个运营数据看板的小项目技术栈选的是前端React 后端Node.js这个选择本身就可以是Spec的一部分——你既然用Spec-kit定义需求干脆把技术栈选型也写进spec里这样AI生成时会严格遵循。首先是项目的初始化。我用Spec-kit的标准流程创建了两个目录一个是/specs存放全项目的规格文件一个是/src存放AI生成的代码。规格文件按模块拆分比如dashboard.md、api.md、>## 技术栈约束 - 前端框架React 18使用函数组件和Hooks禁止使用类组件 - 样式方案Tailwind CSS禁止引入外部UI组件库 - 后端框架Node.js Express禁止使用其他框架 - 数据存储本阶段使用JSON文件模拟数据库不引入数据库依赖 - API规范RESTful风格响应格式统一为 { code, data, message }这些约束看着琐碎但作用很大。它们定义了AI的生成边界避免它自作主张引入一个UI组件库或者换掉整个技术栈。很多Vibe-coding项目最后变成不可维护的代码屎山很大原因就是AI自由发挥太多。3.2 编写第一份spec从需求到验收标准spec是整个流程的灵魂。我在初学Spec-kit时犯过一个错误把spec写成了PRD语言大段大段散文式的描述AI有的地方读不明白有的地方过于笼统最终生成的代码和我的预期差距很大。后来我总结出一套比较稳定的spec写法以看板模块为例### 模块运营数据看板 ### 目标 运营人员打开看板后可以在一屏内查看到昨日核心业务指标和趋势变化。 ### 范围 - 包含访问量统计、销售额统计、订单量统计、各渠道趋势图 - 不包含用户画像模块、告警通知模块、报表导出功能 ### 功能逻辑 1. 指标卡 - 展示昨日PV、UV、销售额、订单量 - 数据来源调用 GET /api/metrics/summary - 展示格式数字需要千分位分隔销售额保留两位小数并显示货币符号 - 刷新方式页面加载时请求一次手动点击刷新按钮可重新请求 2. 渠道趋势图 - 展示最近14天各渠道订单量的趋势变化 - 数据来源调用 GET /api/metrics/channel-trend - 展示顺序按渠道名称首字母排序 - 图表类型折线图各渠道使用不同颜色 - 空值处理某一天某渠道无数据时在折线上断开并标记为null ### 异常状态 - 接口请求失败时在页面顶部展示错误提示条并提供重试按钮 - 加载状态首次进入页面时显示骨架屏禁止使用加载转圈动画 ### 验收标准 1. 启动应用后访问首页可以看到4个指标卡和1个折线图区域 2. 指标卡的数值与后端接口返回的数据一致数值超过9999时显示为1.2万 3. 切换筛选时段折线图数据相应刷新且无页面刷新 4. 在后端接口停止的情况下页面展示错误提示不出现白屏 5. 所有组件文件命名遵循 kebab-case如 metrics-card.tsx这里有几个容易踩坑的细节我必须多说两句。第一验收标准里的每一条都要可验证。比如数值超过9999时显示为1.2万这就是一条明确可测的规则。但如果你写数据展示美观大方AI就完全不知道你要什么。第二异常状态一定要写。很多Vibe-coding生成的代码在一切顺利时跑得很欢一遇到接口报错就白屏或无限loading。Spec里把异常状态作为一等公民定义好AI才能把它写进代码里。第三禁止使用加载转圈动画这种负面约束很重要。AI非常偏爱加载转圈动画几乎所有现代前端工具的默认实现里都有这个东西。你如果不明确禁止它一定会给你加一个Spinner。3.3 让AI按spec生成代码核心技巧spec文件准备好之后进入真正的生成环节。Spec-kit的用法有两种一种是在它的编辑器界面里操作另一种是把spec文件直接丢给支持上下文管理的AI编程工具配合它的提示词工程来生成。我个人的习惯是混合使用。遇到需要精确控制逻辑的模块比如数据聚合逻辑、权限判断逻辑我会把spec文件作为唯一上下文喂给AI而遇到一些纯粹的UI实现比如列表、卡片布局我会在spec基础上额外给一些更感性的描述比如这几个卡片之间要有呼吸感不要挤在一起。这里有一个非常实用的技巧分步生成而不是一次性生成整个项目。我第一次做的时候直接把整份spec丢给AI让它一次性生成全部代码结果AI在生成到第三个模块的时候就开始混乱了——它会在新建组件时把第一个模块的设计模式拿来套用分不清各模块的边界。后来我改变了策略每次只让AI生成一个模块生成完后立即人工review这个模块的代码确认没问题后再进入下一个模块。这个过程叫小步快跑虽然看起来比一次性生成多花了一些时间但从长期维护的角度来看这点时间投入完全是值得的。另外在让AI生成每个模块时我会在提示词里把对应模块的spec原文复制进去并且要求它逐条对照请严格按照以下spec实现渠道趋势图模块。在开始编码之前先列出你对这条spec的理解和可能的疑问点。编码完成后请逐条对照spec中的验收标准做自我检查并把检查结果输出。让AI先复述再干活这一点极其有用。很多时候AI自以为理解了需求其实理解偏了。让它先说出它对这条需求的理解你可以及时纠正偏差。我第一次用这个技巧时AI复述出来的理解里就漏掉了空值断开这个关键逻辑赶紧修正省得生成后返工。4. Spec-kit实战中的常见问题与排查技巧4.1 spec写得不够机器可读AI理解出现偏差怎么办这是上手Spec-kit最常遇到的问题。你以为自己写得够清楚了但AI还是理解得不对。比如我写按天聚合AI可能理解成了按日期字符串排序这两者在处理跨年数据时行为完全不一样。一个可靠的解决方法是在spec里尽量使用结构化的表达方式而不是叙事性的描述。比如按天聚合这种表述本身是有歧义的你应该写成聚合法则以 yyyy-mm-dd 格式的日期字符串作为分组键所有业务数据按照该分组键求和日期升序排列。再比如凡是涉及规则类的需求尽量用如果...那么...的条件句式。它能直接把模糊的语义转成AI可以执行的逻辑结构。我在写spec时但凡有规则都会强制自己写成条件句时间久了这几乎成了肌肉记忆。另一个角度是逆向验证。如果AI生成的代码不符合预期你要先检查是不是spec本身有歧义而不是急着改代码。我统计过在我实际项目中AI理解偏差的case有80%都能追溯到spec文本的模糊表述。改spec比改代码高效得多因为spec是根代码是叶。4.2 迭代过程中的spec漂移怎么防止AI越写越偏项目进入迭代期之后一个新的问题会出现spec漂移。当需求发生变化时你往往只更新了某个模块的spec但其他模块的spec可能已经是几周前写的与当前需求不一致。如果这时候让AI生成代码它可能把新旧不一致的逻辑混合在一起。我遇到过的一个真实案例是看板模块增加了一个渠道对比功能但渠道趋势图的spec没有同步更新对比的前提条件导致趋势图和对比图里的数据口径完全不一致同一时间段的订单量数值对不上号。解决spec漂移问题的办法是迭代时强制走一遍spec影响分析流程。在修改spec之前先检查哪些模块可能受影响——这个环节在大型项目里尤其重要直接影响后续的代码生成质量。流程包括列出需求变更点确定变更所属的功能模块找出该模块的依赖方和关联模块比如趋势图数据源变更了那么指标卡的总量统计是否也有影响逐一更新受影响的spec文件而不是只改一个在spec变更记录摘要里标注清楚本次改动的逻辑差异方便以后追溯这里我有一个具体执行方式用Spec-kit的spec文件头部维护一个变更日志区块格式很简单## 变更记录 - v1.02025-01-15初始版本 - v1.12025-01-18修改渠道趋势图的数据源从 /api/metrics/channel-trend 变更为 /api/metrics/channel-trend-v2新增渠道对比功能 - v1.22025-01-20修复空值处理逻辑断开的折线改为连接虚线有了这个变更记录每次生成代码前AI都能看到清晰的演进轨迹不会把已经废弃的旧逻辑又捡回来。4.3 多人协作时spec管理怎么避免冲突Vibe-coding最常见的使用场景是单人作战但如果你想把它引入一个小团队spec管理就不可避免。一个项目的多个模块会由不同人去和AI交互每个人都带着自己的spec和偏好最后很容易产出风格不一致的代码。我的建议是spec文件的规划/同步/归档这三件事必须由一个人统一牵头管理其他人只提交需求变更申请不在实际文件里直接改。我们把这种模式叫作锚点统一、分支自由。锚点统一指的是项目总纲、技术栈约束、公共模块规范、命名规范这些全局性spec必须是一致的版本不能各改各的。分支自由指的是各功能模块的详细spec允许各模块负责人自行细化。你可以用规格目录 模块负责人的二维划分来管理比如/specs/core——全局共享规格由项目负责人维护/specs/modules/dashboard——看板模块规格由A维护/specs/modules/approval——审批模块规格由B维护分工清楚之后最大的好处是每个人的AI提示词上下文不会互相污染。A在生成看板代码时只需要加载全局规格和看板模块规格完全不需要看到审批模块的内容。另外多人协作时一定要约定代码生成的风格基准。同一个团队里一个人让AI生成组件时偏好把样式写在单独的CSS文件里另一个人偏好用CSS-in-JS最后合并代码时冲突不断。在全局spec里直接用一份代码风格检查清单做统一约束给AI生成时作为必读附加项你就不用在review阶段一遍遍口头强调这些规约了。5. 几个小技巧让Spec-kit用起来更顺手5.1 善用例外追加机制再好的预判也不可能覆盖所有需求。实际开发中总有一些细节需求是你写spec时想不到的。我在做审批小应用时就遇到过这种场景spec里只定义了审批表单的字段和流转逻辑但没定义审批备注超过30个字时输入框要自动增高这种交互细节。这种小细节如果在生成代码之后去改又得回到对话里去描述一堆上下文。我的处理方式是在spec文件末尾增加一个例外追加区块专门用来记录那些在生成过程中发现、但规格里没有覆盖到的细节需求。追加时一句话即可不需要更新整个spec的正式条款。到了下一次生成迭代时这些追加需求会自动被加载AI就会遵守了。5.2 把验收标准的自动化检查做实在我前文提到验收标准要可执行实操上最好的方法就是把它拆成lint规则和单元测试。Spec-kit本身结合测试框架把部分验收标准自动化为断言可以大幅减少人工check的疲劳感。比如我之前做看板时有一条验收标准是接口失败时提示错误条且提供重试按钮。我把它拆成了三条断言渲染错误提示条、点击重试后重新发起请求、请求成功后错误条消失。这三条写在测试文件里每次AI生成完代码跑一下测试这条标准是否满足就一目了然了。这让我不太需要一条条人工检查既省力又精准。能自动化的验收项一定要自动化这个原则落实得越早项目后期你从疯狂人工review里解放出来的时间就越多。5.3 spec的颗粒度别走极端最后说一个很实际的体会spec不是越详细越好。我一开始追求每个模块都写超大篇幅事无巨细全部定义结果AI生成出来的代码嵌套了很多无意义的中间变量——因为它把你写的每一句话都当成需要显式处理的逻辑反而生成了结构性冗余。AI的过度服从与不服从同样糟糕。经过好几轮调试我最后找到了一个相对合适的平衡点spec只定义例外、规则和边界不定义通用的实现方式。通用方案只需要在全局spec里声明一次比如UI采用网格布局模块级spec里就不用再说一次采用网格布局。这样每一份spec的篇幅都控制在必要信息以内AI的准确率和生成效率都大幅提高。我把这种程度的spec戏称为轻量规格——它更像一个给AI的地图而不是一个给AI的填空题答案。地图标记出哪里有山、哪里有河、哪里禁止通行但具体怎么走让AI自己找路。我最终用这个思路做了三个项目整体体验都相当稳定前期写规格文档的时间从最初的三小时缩短到四十分钟后期返工率却至少下降了一半。如果你计划用Vibe-coding做正经的项目我强烈建议你从一份轻量级的spec开始让AI第一次生成时就踩在规格画的边界内然后持续维护这份spec。它不是把你和AI之间的对话记录完整保存而是把你真实想要的那个系统描述得足够清楚让AI的每一次进展都不跑偏。这套工作流我用了很久真心觉得它值得一试。