从Vibe Coding到Spec Coding：AI驱动的软件设计工程化实战

1. 项目概述从“感觉”到“规格”的研发范式跃迁最近和几个技术VP、架构师朋友聊天大家不约而同地提到了一个词Vibe Coding。这词儿挺有意思直译过来是“氛围感编程”说白了就是开发者在面对一个模糊需求时凭借自己的经验、直觉和对业务“氛围”的理解去编写代码。这种模式在过去很长一段时间里尤其是在敏捷开发、快速迭代的创业公司或创新业务线中非常普遍。它的优点是快能快速响应变化快速出原型。但缺点也极其明显代码质量高度依赖个人水平需求理解容易产生偏差技术债务像滚雪球一样累积一旦团队规模扩大或需要长期维护就会变成一场灾难。于是我们开始探索一种更可控、更可预期、更适合规模化团队协作的研发模式。这就是“Spec Coding”即“规格化编程”。它不是要扼杀创造力而是将创造力的发挥建立在清晰、共识的基础上。这个项目就是我们在企业内部推动的一场从Vibe Coding到Spec Coding的工程化实战。它不是空谈理论而是一套包含了工具链、流程规范、团队协作机制和度量体系的完整解决方案目标是将AI驱动的软件设计AI-SDD从概念真正落地到每天的生产代码提交中提升研发的确定性、质量和效率。如果你正面临团队协作效率瓶颈、需求反复变更、线上故障频发或者想引入AI辅助编程但不知如何与现有流程结合那么这篇来自一线的实战总结或许能给你带来一些可以直接“抄作业”的思路。2. 核心理念与体系设计为什么是Spec Coding2.1 Vibe Coding的困境与Spec Coding的破局点Vibe Coding之所以盛行是因为它迎合了“快速试错”的互联网思维。产品经理可能只有一个模糊的想法或者几张草图开发者就开始动手了。沟通成本看似很低大家在一个“频道”上凭感觉推进。但问题会随着时间暴露需求理解的“罗生门”产品、开发、测试三方对同一个功能点的理解可能完全不同直到测试阶段甚至上线后才暴露出认知偏差此时返工成本极高。技术实现的“黑盒”代码为什么这么写当时的决策依据是什么除了原作者其他人很难理解导致后续维护、重构困难重重。质量保障的“后置”测试用例的编写严重滞后于开发甚至依赖于开发完成后的“解释”无法在早期形成有效约束。AI协作的“无力”当你试图让AI如GitHub Copilot、通义灵码等辅助编写一个复杂功能时你给它的提示Prompt本身就是模糊的“Vibe”导致生成的代码质量不稳定需要大量人工修正价值大打折扣。Spec Coding的核心破局点在于将“模糊的氛围”转化为“清晰的规格”。这里的“规格”Specification不仅仅指产品需求文档PRD它是一个更广义的、机器可读或至少是高度结构化的契约集合。它包括业务规格用结构化的方式描述用户故事、验收标准AC、业务流程和业务规则。技术规格包括接口契约API设计文档如OpenAPI Spec、数据结构、关键算法逻辑描述、非功能性需求性能、安全、可用性指标等。测试规格在编码之前定义的测试用例包括正常场景、边界场景和异常场景这其实就是“测试驱动开发TDD”思想的延伸。我们的体系设计目标是让规格成为研发流程中唯一、权威的源头。所有后续活动——设计、编码、测试、AI辅助——都严格围绕规格展开并反向验证和丰富规格。2.2 AI-SDDAI驱动的软件设计的工程化融合AI-SDD不是让AI取代开发者而是让AI成为贯彻Spec Coding理念的“超级助手”。我们的工程化实践将AI深度集成到了规格生成、转换和验证的各个环节从自然语言到结构化规格NL to Spec利用大语言模型LLM将产品经理撰写的自然语言需求甚至是会议纪要自动提取、归纳成结构化的用户故事和验收标准模板形成初步的业务规格草案。这大大减少了人工梳理的成本并保证了格式的统一。从业务规格到技术规格Biz-Spec to Tech-Spec基于业务规格AI可以辅助架构师或资深开发者生成初步的技术设计方案、API接口定义、数据库表结构建议等。开发者在此基础上的修订和确认效率远高于从零开始。从规格到代码骨架与测试用例Spec to Code/Test Skeleton这是AI辅助编码的核心场景。根据清晰的技术规格如一个OpenAPI定义的接口AI可以生成高度可靠、符合团队规范的服务层、控制器层代码骨架以及对应的单元测试、集成测试用例框架。开发者只需填充核心业务逻辑。规格一致性校验Spec Consistency ValidationAI可以持续扫描代码变更检查其是否仍然符合最初定义的API规格、数据模型规格在代码评审Code Review阶段提前发现偏差。这套融合的关键在于AI的效能与输入信息的质量即规格的清晰度强正相关。模糊的Vibe输入只能得到模糊的、需要大量调试的AI输出而清晰的Spec输入则能获得精准、可用性极高的AI辅助。这反过来也激励团队撰写更优质的规格。3. 实战工具链与核心工作流搭建理念需要工具和流程来承载。我们搭建的工具链并非全是自研而是以“规格”为中心对现有优秀工具进行深度集成和定制。3.1 核心工具选型与定位我们摒弃了“全家桶”思维采用“最佳单品”组合策略规格管理平台Notion 自定义数据库模板为什么是Notion因为它足够灵活既能满足产品经理用富文本描述需求又能通过Database属性来结构化信息如优先级、业务模块、关联技术规格ID等。我们建立了统一的“业务需求-用户故事”数据库每个条目都链接到后续的技术和测试资产。自定义模板我们设计了标准的规格模板强制包含“业务目标”、“用户场景”、“验收标准Given-When-Then格式”、“非功能性需求”、“关联API/数据模型”等字段。AI在第一步NL to Spec的输出就直接填充到这个模板中。API设计与协作Stoplight Studio Git为什么是Stoplight它直接支持OpenAPI 3.0标准设计体验优秀并且能基于API规格自动生成直观的文档、Mock Server和代码片段。我们将每个微服务的API规格文件openapi.yaml用Git进行版本管理任何修改都必须通过合并请求Merge Request并与需求条目关联。AI辅助编码核心Cursor 团队知识库为什么是Cursor相比纯粹的代码补全工具Cursor的“Chat with Workspace”和强大的代码库理解能力使其能更好地基于我们项目中的现有规格如OpenAPI文件、架构说明文档进行上下文感知的代码生成。我们为团队购买了许可证并统一了配置。团队知识库我们将项目架构决策记录ADR、代码规范、通用组件使用说明、领域术语表等整理成Markdown文件存放在项目根目录的docs/下。在Cursor中设置这些文件为上下文让AI在生成代码时能遵循团队约定。测试驱动与验证JetBrains IDE本地 持续集成CI在本地我们强调使用IDE的测试框架如JUnit, pytest, Jest先行编写测试。CI管道我们用的是GitLab CI中设置了强制关卡① 代码编译和静态检查SonarQube②基于OpenAPI Spec的接口契约测试使用Schemathesis或Dredd③ 单元测试通过率要求如90%④ 集成测试。只有通过所有关卡代码才能合并。3.2 端到端的工作流闭环我们的核心工作流是一个以“规格条目”为牵引的闭环需求条目化产品经理在Notion中创建需求条目利用AI插件辅助生成结构化的验收标准。条目状态为“待细化”。技术规格拆解技术负责人或架构师认领条目在Stoplight中设计或更新API在Notion中补充技术方案要点并将API Spec的Git链接关联到需求条目。状态变为“技术就绪”。开发启动开发者领取“技术就绪”的条目。第一步不是在IDE里写代码而是运行脚本根据API Spec在本地生成Mock Server用于前端并行开发。根据业务规格和技术方案在IDE中先编写测试用例描述期望行为。使用Cursor结合API Spec和刚写的测试用例生成符合契约的代码骨架。填充业务逻辑运行测试直至全部通过。提交与验证代码提交后CI管道自动运行。契约测试会确保实现与OpenAPI Spec完全一致静态扫描确保代码质量测试覆盖率报告被更新。开发者将代码关联的Git Commit链接回填到Notion需求条目。评审与合并评审者Reviewer的焦点发生变化。他不再需要费力理解“这段代码要干嘛”而是重点审查① 代码实现是否满足了Notion中列出的所有验收标准② 是否遵循了架构决策和代码规范③ 对于复杂逻辑开发者是否在代码注释中引用了相关的规格条目ID评审通过后合并。闭环与度量需求条目状态标记为“已完成”。我们通过仪表盘度量“需求条目从创建到关闭的平均周期”、“因规格不清晰导致的返工率”、“AI生成代码的采纳率”等指标持续优化流程。注意这个流程初期会感觉“繁琐”因为它将很多Vibe Coding模式下隐性的、脑内的沟通和工作显性化了。但正是这种显性化带来了确定性和可规模化。团队需要大约2-3个迭代周期来适应。4. 关键环节的实操细节与避坑指南4.1 如何撰写“AI友好型”业务规格规格的质量直接决定AI辅助的效能。我们总结了“AI友好型”业务规格的要点使用结构化模板强制使用“Given-When-Then”格式编写验收标准。例如Given用户已登录且购物车中有商品A单价100元和商品B单价200元。When用户点击“结算”按钮。Then系统生成一个订单订单总金额为300元状态为“待支付”并清空用户的购物车。为什么有效这种结构极度清晰不仅利于AI理解也利于后续手动编写测试用例几乎可以1:1转换成测试代码。明确定义业务规则和边界不要写“系统要处理优惠券”。要写“系统处理优惠券的规则1. 每笔订单只能使用一张平台券2. 店铺券可与平台券叠加3. 优惠券金额不能超过订单总金额的50%”。将规则枚举化。关联术语表在团队知识库中维护一份“领域术语表”例如“什么是‘平台券’什么是‘店铺券’”。在规格中引用这些术语并让AI上下文包含术语表可以避免歧义。避免模糊的形容词将“快速响应”改为“接口P99响应时间 200ms”将“用户体验好”转化为具体的操作步骤和界面元素描述。踩坑实录初期我们让产品经理自由发挥结果AI生成的代码五花八门。后来我们提供了一个带有示例和字段校验的Notion模板并安排了一次培训专门讲解如何写出对开发和AI都友好的需求质量立竿见影。4.2 基于OpenAPI Spec的契约驱动开发实战这是连接业务与技术的关键桥梁。我们的实践超越了简单的文档生成。设计优先坚决执行“设计优先”Design-First原则。在写一行代码之前团队至少包括产品、后端、前端要对API的路径、参数、请求/响应体、错误码达成一致并体现在openapi.yaml文件中。这本身就是一个消除歧义的过程。利用工具生成“活”的资产自动生成Mock Server使用prism或Stoplight自带的mock功能。前端开发者无需等待后端即可基于真实的、动态的响应数据进行联调。命令很简单prism mock openapi.yaml。自动生成客户端SDK/服务端骨架使用openapi-generator。在CI流程中每当openapi.yaml更新并合并到主分支自动触发生成最新版的TypeScript前端API客户端和Java Spring Boot服务端接口Controller开发者只需实现其中的逻辑。这保证了API契约的严格同步。# 示例在CI脚本中生成Java服务端接口 docker run --rm -v ${PWD}:/local openapitools/openapi-generator-cli generate \ -i /local/openapi.yaml \ -g spring \ -o /local/generated-server-code \ --additional-propertiesinterfaceOnlytrue契约测试作为质量门禁这是最关键的一环。我们使用schemathesis它能基于OpenAPI Spec自动生成大量的、随机的测试用例对运行中的服务进行“模糊测试”以发现违反契约的边界情况。# 对运行在 http://localhost:8080 的服务进行契约测试 schemathesis run --checks all http://localhost:8080/openapi.json我们将这个命令集成到CI中针对每个合并请求MR部署的预览环境进行测试。如果测试失败MR无法合并。这从根本上杜绝了“代码实现与文档不符”的经典问题。避坑指南OpenAPI Spec本身也需要版本管理和评审。我们要求对openapi.yaml的任何修改即使是修正一个错别字都必须通过MR并且需要前端和后端开发者共同评审。我们约定不兼容的变更如删除字段、修改字段类型必须升级API版本号如/api/v2/xxx。4.3 让AI成为高效的“结对编程”伙伴Cursor等AI编码助手的使用需要技巧而不是简单地提问。提供精准的上下文打开“代码库检索”功能让AI能感知你整个项目的结构。在对话中主动提供关键信息不要只说“帮我写一个用户登录函数”。应该说“根据项目docs/auth-spec.md中的设计使用bcrypt进行密码哈希使用jjwt生成JWT令牌参考service/UserServiceImpl.java的代码风格帮我实现AuthService接口的login方法。请求体结构见openapi.yaml中/auth/login路径的定义。”使用“”引用文件在Cursor的聊天框中你可以用符号引用项目中的特定文件如openapi.yamlAI会将其内容作为上下文。分步骤、迭代式生成不要期望AI一次性生成一个完美的、复杂的类。先让它生成接口定义再生成实现类骨架然后针对某个具体方法生成代码最后让它为你生成的代码编写单元测试。这种“对话式开发”效率更高。生成的代码必须经过审查和测试AI生成的代码是“建议”不是“圣旨”。开发者必须理解每一行代码运行测试确保其符合业务逻辑和团队规范。我们要求所有AI生成的大块代码超过10行在提交时必须在Commit Message中注明#aicode以便评审者重点关注。构建团队共享的Prompt库我们将一些高效的、针对特定场景的Prompt保存下来形成团队知识。例如“根据OpenAPI Spec生成Spring Boot Controller的Prompt”、“为这个Service方法生成Mockito单元测试的Prompt”。实操心得AI在编写样板代码Boilerplate Code、数据转换逻辑、简单的CRUD操作以及根据清晰描述生成测试用例方面表现非常出色能节省大量时间。但对于复杂的业务算法、需要深度领域知识的逻辑它仍然力不从心。开发者的核心价值正从“编写代码”向“定义问题、设计规格、审查和整合AI输出”转移。5. 团队协作变革与常见问题排雷5.1 角色职责的重新定义推行Spec Coding和AI-SDD意味着团队角色职责的演变产品经理从“需求描述者”变为“规格定义者”。需要更结构化、更精确地表达需求并积极参与技术规格的评审确保业务意图被准确翻译。架构师/技术负责人重心从“解决技术难题”部分转移到“设计清晰契约”和“制定规格标准”。他们是规格质量的守门人。开发者从“代码实现者”变为“规格实现与AI协作专家”。需要具备更强的规格理解能力、测试驱动开发能力和AI工具使用技巧核心工作是确保代码精确满足规格。测试工程师角色不是被削弱而是升级。他们更早介入参与验收标准的制定并专注于编写更复杂的集成测试、端到端测试和性能安全测试。他们利用AI生成的基础测试用例进行补充和深化。5.2 推行过程中的典型阻力与应对“这太慢了不如直接写代码快”现象在项目初期尤其是面对简单功能时团队成员会觉得写规格、画流程图是浪费时间。应对不追求100%全覆盖。我们采用“渐进式规格化”策略。对核心业务流程、公共接口、复杂算法必须编写规格对简单的、一次性的内部工具可以适当放宽。同时用数据说话统计在采用新流程后因需求理解错误导致的返工工时的下降比例以及线上缺陷率的下降证明“前期慢是为了整体快”。规格与代码实际“两张皮”现象规格写完后就被遗忘代码改了规格没更新。应对通过工具强制关联。我们的CI门禁契约测试确保了代码必须符合API Spec。同时在代码评审中要求开发者说明代码变更对应的规格条目IDNotion中的链接。将规格更新作为代码合并的前提条件之一。AI生成代码质量参差不齐现象开发者盲目信任AI引入bug或不符合规范的代码。应对强化代码评审和测试。建立明确的规则AI生成的代码必须经过严格审查必须配套有通过的单元测试在团队内定期分享“优质Prompt”和“AI生成代码的常见陷阱”案例提升全员能力。历史项目如何改造现象存量系统庞大缺乏任何规格文档。应对“新人新办法老人老办法”。对于新功能、新模块强制使用新流程。对于老系统在对其进行重大重构、修复复杂Bug或需要深入理解时利用AI进行“反向工程”让AI分析现有代码尝试生成对应的接口说明、流程图或概要设计文档。这既是补充规格的过程也是理解系统的好方法。5.3 效果度量与持续改进我们建立了几个关键指标来衡量这套体系的效果需求交付周期从创建到上线目标是稳定或缩短。初期可能会因流程学习而变长但长期应由于返工减少而缩短。线上缺陷密度每千行代码的缺陷数核心监控指标预期应有显著下降。规格变更率在开发启动后对已确认规格的修改次数。这反映了前期规格工作的质量目标是降低。AI代码采纳率在评审中未被修改直接采纳的AI生成代码行数占比。反映了AI辅助的有效性和规格的清晰度。团队满意度调研定期匿名调研了解开发、测试、产品同学对新流程的感受收集改进意见。推行半年后我们的数据显示线上由需求歧义和接口不一致引发的缺陷下降了60%以上核心需求的交付周期波动范围缩小变得更加可预测。更重要的是团队对新成员 onboarding 的速度大大加快因为所有知识都沉淀在了结构化的规格和知识库中。从Vibe Coding到Spec Coding本质上是一场研发范式的工业化升级。它用清晰的契约取代模糊的默契用可重复的工具流程取代个人的灵光一现用人与AI的协同取代低效的重复劳动。这条路开始可能有些磕绊需要改变习惯、投入学习但一旦跑通它为团队带来的确定性、质量和长期效能提升是那些依赖“氛围感”和“英雄主义”的项目所无法比拟的。这场变革始于一份清晰的结构化需求成于一套坚定的工程化实践。