Spec-Kit规范驱动开发：让AI编码从氛围编程走向工程化

1. 从“氛围编程”到规范驱动为什么我们需要重新审视AI编码方式“氛围编程”这个词最近半年在开发者圈子里流传得特别广。说白了就是打开AI编程助手用自然语言描述一下想要什么然后看着它噼里啪啦生成一大段代码感觉对了就复制粘贴感觉不对就重新生成一版。整个过程靠的是“感觉”和“氛围”而不是严谨的工程规范。我身边不少朋友一开始都这么干包括我自己也经历过这个阶段——确实爽效率看起来很高但问题很快就暴露了。最典型的场景是这样的你让AI帮你写一个用户注册模块它给你生成了路由、控制器、数据模型、验证逻辑看起来挺完整。但当你把它集成到现有项目里时发现命名风格跟项目里其他模块完全不一致错误处理的方式也跟团队约定不一样甚至连目录结构都是AI自己“发明”的。于是你不得不花大量时间做适配和重构原本省下来的时间又还回去了。更麻烦的是当多人协作时每个人用AI生成代码的风格都不一样代码库很快就变成了一锅粥。这就是“氛围编程”的核心问题它把AI编码变成了一种个人艺术创作而不是可重复、可验证、可协作的工程实践。GitHub Spec-Kit 的出现正是为了解决这个根本矛盾。它提出的SDDSpec-Driven Development规范驱动开发理念核心思想非常朴素但极其有力在让AI写代码之前先把“要做什么”和“怎么做”用结构化的规范文档定义清楚然后让AI严格按照规范来生成代码。Spec-Kit 本质上是一套工具集和流程框架它帮你把模糊的需求转化为精确的规范再基于规范驱动AI完成编码。你可以把它理解成给AI编码加了一套“工程图纸”——以前是让AI自由发挥现在是让AI照着图纸施工。这个转变的意义在于它让AI编码从“碰运气”变成了“可预期”从“个人手艺”变成了“团队工程”。适合谁来用这套东西如果你是一个人写点小工具、做点实验性项目说实话“氛围编程”可能就够了Spec-Kit 的流程反而显得重。但如果你在团队里工作或者你的项目需要长期维护、多人协作、有明确的交付标准那 Spec-Kit 这套思路就非常值得认真研究。它解决的不是“AI能不能写代码”的问题而是“AI写的代码能不能直接用在正经项目里”的问题。2. Spec-Kit 核心机制拆解规范到底是怎么驱动开发的2.1 规范文档的结构化设计Spec-Kit 最核心的产出物就是规范文档。但这里的“规范”不是我们平时写的那种模糊的需求描述而是一套结构化、机器可读、AI可理解的文档体系。我研究下来它大致包含几个层次第一层是功能规范描述“做什么”。比如“用户可以注册账号需要邮箱验证密码强度有要求”。这一层用的是接近自然语言但结构化的格式确保人和AI都能准确理解。第二层是技术规范描述“怎么做”。包括技术栈选择、架构模式、接口定义、数据模型、错误处理策略等。这一层会精确到具体的框架版本、目录结构、命名约定。第三层是任务分解把规范拆解成AI可以逐个执行的具体任务。每个任务都有明确的输入、输出和验收标准。这种分层设计的精妙之处在于它把“意图”和“实现”彻底分开了。以前我们让AI写代码是把意图和实现混在一起说AI经常理解偏。现在先写清楚意图再写清楚实现约束最后拆成任务AI的执行准确率会大幅提升。2.2 规范如何约束AI的生成行为Spec-Kit 约束AI的方式不是简单的“提示词工程”而是通过规范文档本身的结构来限制AI的自由度。我举个具体例子你就明白了。假设你要做一个博客系统的文章列表接口。在“氛围编程”模式下你可能会说“帮我写一个获取文章列表的API”。AI会给你生成一个能用的接口但具体用什么框架、返回什么格式、分页怎么做、错误码怎么定义全看AI当时的心情。而在 Spec-Kit 模式下你的规范文档里会明确写框架Express.js 4.x路由GET /api/v1/articles查询参数page默认1、limit默认20最大100、tag可选响应格式{ code: 0, data: { list: [], total: 0, page: 1 }, message: success }错误处理参数校验失败返回 code: 400服务器错误返回 code: 500命名规范文件名用 kebab-case变量用 camelCase当这些约束都写清楚之后AI生成出来的代码就完全不一样了。它不会“发明”新的响应格式不会用奇怪的命名不会漏掉参数校验。规范文档就像给AI戴上了一副“镣铐”但正是这副镣铐让生成的代码可以直接融入项目。2.3 与传统开发流程的对比我整理了一个对比表格能更直观地看出差异维度氛围编程Spec-Kit 规范驱动需求表达口头描述模糊结构化文档精确AI角色自由创作者规范执行者代码风格每次可能不同严格统一协作友好度低各写各的高规范共享返工率高经常需要重构低一次成型率高适用场景原型、实验生产项目、团队协作学习成本低中需要学习规范写法长期维护困难容易规范即文档这个对比不是说“氛围编程”一无是处。快速验证想法的时候氛围编程确实快。但一旦进入正式开发阶段Spec-Kit 这套方法的优势就非常明显了。2.4 规范驱动开发的核心价值Spec-Kit 带来的最大价值我认为是把AI编码从个人行为变成了团队资产。以前每个人用AI生成的代码只有他自己能看懂为什么这么写。现在规范文档是共享的任何人拿到规范都能理解项目的设计意图AI也能基于同一份规范生成风格一致的代码。另一个容易被忽视的价值是可追溯性。当代码出问题时你可以回溯到规范文档看看是规范本身有问题还是AI没有正确执行规范。这种可追溯性在团队协作和长期维护中极其重要。还有一个实际的好处是降低了对AI“聪明程度”的依赖。规范写得越清楚对AI理解能力的要求就越低。这意味着你可以用更小的模型、更低的成本获得更稳定的输出。我实测下来同一份规范用不同级别的AI模型生成代码质量差异比“氛围编程”模式下小得多。3. 实操落地从零开始用 Spec-Kit 驱动一个完整项目3.1 环境准备与工具安装Spec-Kit 本身是一个开源工具集你可以直接从 GitHub 上获取。这里我不展开具体的下载方式重点讲安装后的配置思路。安装完成后你需要在项目根目录初始化 Spec-Kit 的工作空间。它会创建几个关键目录specs/存放功能规范文档plans/存放技术实现方案tasks/存放任务分解清单templates/存放规范模板初始化命令大致是这样的spec-kit init --project-name my-blog --template standard这个命令会生成一套默认的规范模板你可以根据自己的项目类型选择不同的模板。比如 Web 应用、CLI 工具、库开发模板结构会有所不同。注意初始化之前确保你的项目目录是干净的Spec-Kit 会检查目录结构如果已有同名文件可能会冲突。建议在空目录或者新分支上操作。3.2 编写第一份功能规范功能规范是整个流程的起点。我以“用户注册”功能为例展示一份规范应该怎么写。# 功能规范用户注册 ## 功能描述 允许新用户通过邮箱和密码创建账号。 ## 输入 - 邮箱必填符合邮箱格式唯一 - 密码必填最少8位包含字母和数字 - 确认密码必填与密码一致 ## 输出 - 成功返回用户ID和创建时间 - 失败返回具体错误信息 ## 业务规则 1. 邮箱不能重复注册 2. 密码需要加密存储 3. 注册成功后自动发送验证邮件 4. 未验证邮箱的用户不能登录 ## 边界条件 - 邮箱长度不超过254字符 - 密码长度不超过128字符 - 同一IP每分钟最多注册5次这份规范看起来简单但它把AI需要知道的所有关键信息都覆盖了。AI拿到这份规范就不会问“密码要不要加密”“邮箱要不要唯一”这种问题直接按规范执行。3.3 技术方案与架构约束定义功能规范写完后下一步是技术方案。这一步要定义清楚“用什么技术、按什么结构、遵循什么约定”。# 技术方案用户注册 ## 技术栈 - 语言TypeScript 5.x - 框架Express.js 4.x - 数据库PostgreSQL 15 - ORMPrisma 5.x - 密码加密bcrypt - 邮件服务nodemailer ## 目录结构 src/ modules/ user/ user.controller.ts user.service.ts user.repository.ts user.schema.ts user.types.ts ## 接口定义 POST /api/v1/users/register Request Body: { email: string, password: string, confirmPassword: string } Response: { code: 0, data: { userId: string, createdAt: string }, message: success } ## 命名约定 - 文件名kebab-case - 类名PascalCase - 变量/函数camelCase - 常量UPPER_SNAKE_CASE ## 错误处理 - 参数校验失败code 400 - 邮箱已存在code 409 - 服务器错误code 500这份技术方案就是AI的“施工图纸”。它精确到文件命名和错误码AI生成代码时几乎没有自由发挥的空间。3.4 任务分解与AI执行有了功能规范和技术方案接下来就是拆任务。Spec-Kit 的任务分解通常按依赖关系排序创建数据库模型和迁移文件实现数据访问层repository实现业务逻辑层service实现控制器层controller编写参数校验逻辑集成邮件发送功能编写单元测试编写集成测试每个任务都可以单独交给AI执行。因为规范已经写得很清楚AI在每个任务上的表现都会很稳定。我实测下来一个中等复杂度的模块用这种方式生成代码首次通过率能从氛围编程的30%左右提升到70%以上。3.5 验证与迭代AI生成代码后你需要对照规范做验证。Spec-Kit 提供了一些辅助命令可以检查代码是否符合规范中的命名约定、目录结构、接口定义等。spec-kit verify --spec specs/user-register.md --code src/modules/user/这个命令会输出一份检查报告告诉你哪些地方符合规范哪些地方有偏差。有偏差的地方你可以让AI重新生成或者手动修正后更新规范。实操心得不要指望一次就能写出完美的规范。我通常的做法是先写一版规范让AI生成代码然后根据生成结果反过来完善规范。迭代两三轮之后规范就非常精确了后续类似功能的开发效率会越来越高。4. 常见问题与排查技巧实录4.1 规范写得太细还是太粗这是新手最容易纠结的问题。我的经验是规范要细到AI不会产生歧义但不要细到限制实现自由。举个例子“密码需要加密存储”这句话AI可能会用MD5也可能会用bcrypt。如果你有明确要求就要写“密码使用bcrypt加密salt rounds为10”。但如果你不关心具体算法只要求安全那写“密码需要加密存储”就够了AI选什么算法都行。判断标准很简单如果AI的选择会影响后续开发或者团队协作那就写细如果只是实现细节不影响外部行为就可以粗一点。4.2 AI不按规范执行怎么办有时候你规范写得很清楚但AI生成代码时还是“跑偏”了。常见原因有几个规范文档太长AI的注意力被分散了规范中有矛盾的地方AI不知道听谁的规范用的语言太模糊AI理解偏了排查思路先检查规范文档有没有前后矛盾的地方然后看关键约束是不是放在显眼位置。我通常会把最重要的约束放在规范文档的开头并且用加粗标注。如果还是不行就把任务拆得更细。一个任务只做一件事AI的执行准确率会高很多。4.3 多人协作时规范怎么管理团队使用 Spec-Kit 时规范文档本身也需要版本管理。我的建议是规范文档跟代码放在同一个仓库规范的修改走代码审查流程每个规范文档标注负责人和最后更新时间重大变更需要团队讨论确认这样能避免“规范写了没人看代码写了没人管”的情况。4.4 常见问题速查表问题现象可能原因解决思路AI生成的代码风格不统一技术方案中命名约定不明确补充命名规范给出示例AI漏掉边界条件功能规范中边界条件描述不清用列表逐条列出边界条件生成的接口跟现有项目不兼容技术方案未定义接口规范补充接口定义和错误码规范任务执行顺序混乱任务分解未考虑依赖关系按依赖关系重新排序任务规范更新后AI仍按旧规范生成缓存或上下文未刷新清除缓存重新加载规范文档生成的测试用例覆盖不全规范中未明确测试要求在规范中增加测试覆盖要求4.5 避坑技巧与经验总结踩过几次坑之后我总结了几个实用技巧技巧一规范文档用模板起步。Spec-Kit 自带的模板已经覆盖了大部分场景不要从零开始写。在模板基础上修改效率高很多。技巧二先写验收标准。在写功能规范之前先想清楚“怎么算做完了”。把验收标准写在规范最前面AI生成代码时会更有目标感。技巧三规范文档保持更新。代码改了规范没改下次AI生成就会出问题。我习惯在每次代码合并后检查一下规范是否需要同步更新。技巧四不要过度依赖AI。Spec-Kit 是辅助工具不是万能药。关键的业务逻辑和架构决策还是需要人来把关。AI擅长的是按规范执行不擅长做架构判断。技巧五从小项目开始练手。如果你之前没用过 Spec-Kit先拿一个内部工具或者小模块试试。熟悉流程之后再推广到核心项目。5. 规范驱动开发的边界与适用性思考Spec-Kit 这套方法虽然好但也不是银弹。我实际用下来发现它有几个明显的边界。第一它不适合探索性项目。如果你自己都不知道要做什么规范根本写不出来。这种情况下先用氛围编程快速试错等方向明确了再上 Spec-Kit。第二它对规范编写者的要求不低。写一份好的规范需要你对业务和技术都有清晰的理解。如果规范写得很烂AI生成的代码只会更烂。所以团队里需要有一个人专门负责规范的编写和维护。第三它增加了前期工作量。写规范、拆任务、定义接口这些都需要时间。对于小项目来说这个投入可能不划算。但对于中大型项目前期多花的时间会在后期维护和协作中加倍省回来。第四它不能替代代码审查。AI按规范生成的代码仍然需要人工审查。规范只能保证“形式正确”不能保证“逻辑正确”。业务逻辑的合理性、边界情况的处理还是需要人来判断。我个人的体会是Spec-Kit 最大的价值不在于让AI写出更好的代码而在于让团队对“要做什么”达成共识。很多时候代码出问题不是因为AI不行而是因为大家对需求的理解就不一致。规范文档强制你把模糊的想法变成清晰的文字这个过程本身就能发现很多问题。后续如果要扩展我觉得有几个方向值得尝试一是把规范文档和自动化测试打通规范即测试用例二是把规范文档和API文档生成打通规范即接口文档三是建立规范模板库不同项目类型复用同一套规范模板。这些方向都能进一步提升规范驱动开发的效率。最后分享一个小技巧如果你觉得写规范太枯燥可以反过来让AI帮你写规范。你先用自然语言描述需求让AI生成一版规范草稿然后你在草稿上修改。这样既降低了写规范的门槛又保证了规范的完整性。我最近几个项目都是这么干的效率提升很明显。