最近团队复盘一个内部管理系统时发现从需求到上线只用了两周但真正由人逐行写出来的代码不到三成。这种开发方式在圈子里最流行的叫法是 vibe coding我对它的态度一直很明确靠自然语言让 AI 把东西跑起来确实快但撑不起一个需要长期维护、多人协作、随时可能出线上事故的全栈项目。真正能让 AI 全栈开发落地的是把它升级成带约束的工程化协作——也就是你在很多讨论里看到的那套 harness × sdd 组合拳。这篇文章基于我过去一年在几个真实项目里用 AI 辅助完成全栈开发的经验梳理了一套可以直接复用的最佳实践涵盖模型与工具选型、统一网关接入、规格先行工作流、全栈各层的 AI 落点、质量护栏以及高频事故的完整排查思路。内容会比较细新手建议从第二章工作台搭建看起已经在用 Cursor、Claude Code 却总觉得生成代码不靠谱的直接跳到第三章和第六章那里是我踩坑最多的部分。1. 为什么vibe coding撑不起真正的全栈交付1.1 vibe coding 的甜与苦vibe coding 这个词流行起来之后很多人把它理解成用大白话描述需求AI 把代码吐出来能跑就行。这个模式刚上手时确实很爽你要一个管理后台的列表页一句话下去表格、分页、筛选、弹窗全有了那种人机合一的心流体验特别容易上头。但全栈项目不是单个页面也不是单次生成。它是一套由接口、数据模型、权限边界、错误处理、构建流程、部署配置交织在一起的长生命周期系统。当项目超过三五个文件、几十个函数之后靠感觉让 AI 自由发挥的代价开始指数级上升。我见过团队里一个同事用 vibe coding 两天写完整套用户模块看起来很完整结果联调时发现AI 自己给接口加了 JWT 鉴权但前端登录接口根本没过网关数据库模型里把软删除字段当成普通字段处理所有统计查询都不对。甜的地方在于效率苦的地方在于失控。vibe coding 默认了模型能理解你的隐含意图但大模型的本质是一个概率生成器它在上下文不足时会主动用自己训练数据里的常见方案填补空白。你心里想着简单做个 session 登录就行它默认给你一套 JWT 刷新令牌 Redis 黑名单工程上是标准答案但和你的业务场景完全是两个世界。1.2 从自然语言直觉到规格驱动开发的转向所以问题不是AI 能不能写代码而是AI 在没有明确边界的情况下会擅自替你做一千个小决定。解决方案也很直接把自然语言的感觉替换成结构化的规格。这就是规格驱动开发Spec-Driven DevelopmentSDD的核心逻辑。所谓规格不是几十页的 Word 需求文档而是把用户故事、验收标准、数据模型、接口契约、错误处理这些生成代码所需的最小约束集先写清楚。AI 写代码是在做翻译翻译的质量取决于源语言是否精确。我打个比方你让一个非常能干的新同事去做一个功能你只说把用户登录做了他会按照自己上一家公司的经验来。但如果你把用户名密码校验、失败三次锁 5 分钟、保持会话 24 小时、前后端字段命名规范、日志要打哪些点全部写进任务卡他做出来的东西才会是你想要的。SDD 就是给 AI 写这种任务卡。1.3 我踩过的第一个大坑讲一个真实案例。去年做一个文件上传功能我当时偷懒直接让 AI 实现后端接收文件并保存。AI 生成了一套基于云对象存储 SDK 的方案代码写得很漂亮还有分片上传和进度回调。问题是我们的项目部署在内网服务器存储方案早就定了是本地磁盘加 Nginx 静态目录服务。结果这一版代码在联调阶段才暴露问题我花了一整天改造接口、去掉 SDK 依赖、重新处理临时文件权限。这件事给我最大的教训是AI 生成代码之前必须先给它不允许做什么的约束。后来我养成了习惯任何 AI 生成的模块在动手之前先输出一段约束清单哪些依赖不能用、哪些目录不能动、外部服务有哪些边界、性能指标是什么。把约束写进规格AI 的发挥空间被限制在你允许的范围内出错概率立刻小了一个数量级。2. 搭建一套能打的全栈 AI 工作台模型、网关与上下文2.1 模型分工让不同模型干各自擅长的事很多人的第一个误区是所有任务都用一个最强的模型。我实测下来全栈开发链路里的任务类型差异很大强弱模型混用不仅在成本上更划算质量也更稳定。我现在的分工大概是这样任务类型模型侧重点选择逻辑架构设计与任务拆解推理能力强、上下文窗口大需要综合理解多个模块和约束业务代码生成代码能力均衡、遵循指令稳定高频调用兼顾速度与质量代码审查与重构长上下文、擅长找差异能对比多文件并给出精准修改建议重复性模板代码速度快、成本低如 CRUD、表单、脚手架不值得用贵模型这里有一个很实际的判断标准凡是改错代价高的步骤用强模型比如架构设计、跨模块重构、安全敏感代码凡是生成后有人工审查兜底的步骤可以用中档模型比如样板代码、测试数据、配置片段。我自己在 IDE 里会配置两套快捷键一套走强模型做生成一套走快模型做补全长期下来效率差距很明显。2.2 统一网关层多模型源接入与管理当团队不只一个人用 AI且要对接多个模型服务商时我强烈建议在模型和应用之间加一层统一网关。这也是那类 litellm proxy 工具的核心价值对外暴露一个 OpenAI 兼容接口对内把请求路由到不同的模型后端。我举个例子我们的网关配置会维护一份路由表把代码生成结构化输出会话问答分别指向不同的模型同时统一做令牌计数、成本统计和限流。好处有三个第一应用层代码不需要关心底层模型是谁换模型只改网关配置第二成本和用量可以按项目、按成员统计避免月底对账对到怀疑人生第三可以设置 fallback主模型服务不稳定时自动降级到备用模型不会让整个开发流程卡死。配置上并不复杂核心就是一个路由文件加一个代理服务。我见过很多个人开发者嫌麻烦跳过这一步直接在代码里写死各家 SDK等到要切换模型或者排查请求异常时才发现每个模块的调用方式都不一样改起来痛不欲生。2.3 上下文工程规则文件、项目知识和提示词的沉淀模型能力再强记不住你的项目背景也是白搭。我见过太多人抱怨AI 生成的代码风格和项目不一致根因几乎都是没有给 AI 足够的项目上下文。我的做法是三层上下文管理。第一层是仓库根目录的规则文件比如AGENTS.md里面写清楚项目用什么框架、代码风格偏好、目录结构约定、禁止使用的依赖、测试命令怎么跑。这层内容是每个文件和每次对话都能自动带上的相当于是公司入职手册。第二层是模块级的说明文档放在对应目录下描述这个模块的业务规则和关键设计决策AI 在改动这个目录时会优先读到。第三层是提示词模板把我经常要 AI 执行的几类任务生成接口、写迁移脚本、补测试固化成语料每次只填参数避免现场编 prompt 漏掉关键信息。这三层看起来都是文字工作但它们是让 AI 从通用程序员变成了解你项目的同事的关键。规则文件请务必提交到 Git 仓库跟着代码一起走因为上下文本身就是工程资产。3. 规格先行SDD 工作流如何把 AI Agent 关进笼子里3.1 一份合格规格说明书应该包含什么我见过很多团队写 spec 只写我们要做一个什么功能等 AI 生成完代码再逐条检查这等于让 AI 先射箭再画靶。真正好用的规格说明书至少要有六部分用户故事谁在什么场景下要解决什么问题验收标准可验证的行为描述而不是响应要快这种模糊措辞数据模型实体、字段、类型、关系、约束接口契约路径、方法、请求参数、响应结构、错误码边界与异常权限校验、超时处理、重复提交、数据不存在等情况非功能约束性能指标、兼容性要求、安全规范。举个例子用户注册这个功能普通描述是用户能通过手机号注册合格规格里则要写清楚验证码有效期、手机号格式、密码强度策略、已注册手机号的返回错误码、并发注册时唯一索引冲突的处理方式、注册成功后的默认状态。AI 有了这些约束生成的代码就不再是看起来合理的通用实现而是真正贴合业务要求的实现。3.2 harness 模式用模板与检查清单约束每个生成步骤harness这个词听起来玄乎实际上就是给 AI 的每一个输出动作设置轨道。vibe coding 的问题在于轨道太宽AI 想往哪走往哪走harness 则是把轨道变窄限定输出格式、限定文件范围、限定依赖范围、限定必须通过哪些检查才能继续下一步。我在项目里落地的最基本的 harness 是这样的每次让 AI 实现一个任务前先让它输出一份实施计划计划里必须包含受影响的文件列表、依赖变化清单、测试方案。这份计划经过我确认后AI 才被允许开始写代码。写完之后它必须对照任务卡里的验收标准逐项自检然后在提交说明里列出每一条验收标准的自检结果。这套流程的实质是把 AI 的隐式决策强制变成显式声明。AI 没法再偷偷摸摸地改掉你的依赖或者绕过某个校验因为每一步都有交代。刚开始做会觉得流程冗余但当你同时推进五六个功能、项目里又有很多历史包袱时这套约束救过我无数次。3.3 从规格到代码任务拆解与增量生成的实操流程SDD 的落地流程我总结为四步每一步都在上一层的基础上缩小范围写规格把需求转成上文说的六部分规格这份文档是后续所有步骤的唯一依据拆任务让 AI 根据规格生成任务清单每个任务只干一件事比如创建 user 表迁移、实现注册接口、实现前端注册表单任务之间保持依赖清晰逐个实现把当前任务相关的规格片段、上下文文档、既有代码结构一次性喂给模型让它只生成这个任务的代码然后立刻跑测试验收与合并任务通过测试和审查后合并进主干同时更新规格状态。增量生成的关键是不要让 AI 同时改 20 个文件。一次生成的文件数越少出问题的范围就越小排查成本就越低。我有一次让 AI 一口气重构三个模块结果它把公共工具函数复制了三份每个模块各自维护一份后续修 bug 时三处行为不一致花了两天才收拾干净。从那以后我严格限制单次生成的代码量宁可多跑几轮对话。3.4 规格变更时如何避免代码失控需求变更是全栈开发的常态AI 协助下的变更管理和传统开发有个完全不同的注意点不要直接让 AI改代码而是先让 AI改规格。比如需求方说注册流程要加一个邀请码字段我会先把变更落到规格文件里更新数据模型、接口契约、前端表单说明然后再让 AI 根据更新后的规格去调整代码。这么做的原因是如果直接让 AI 改代码它只会局部地把字段加上但校验逻辑、错误提示、测试用例、接口文档这些关联产物大概率会被遗漏。规格是单一事实来源规格变了AI 才能把关联影响全部找出来。如果变更比较大我还会让 AI 先生成一份影响分析列出受影响的文件、需要同步更新的测试、可能破坏的现有行为。这个分析本身也是一个 harness 约束避免 AI 闷头改代码改到一半发现方向错了。4. 全栈链路里的 AI 落点后端、数据与前端的高效协作4.1 后端生成接口设计先行代码只是翻译后端开发用 AI 时我强烈建议采用接口优先的方式。先让 AI 根据规格生成一份 OpenAPI 文档这份文档定义了所有接口的路径、参数、请求体和响应结构。确认无误后再让它对照 OpenAPI 实现具体逻辑。这样做的好处是接口契约在开发早期就被固定下来了前端可以并行开发后端也不用担心AI 自作主张给响应对象换个字段名。我在实践中发现AI 生成的接口层代码路由、参数校验、序列化质量通常不错真正容易出问题的是业务规则部分所以我会在提示词里明确要求接口的入参出参完全以 OpenAPI 为准业务异常用统一错误码不允许在 controller 里写复杂业务逻辑。这样生成的代码层次很清楚后续维护省非常多力气。4.2 数据层schema、迁移与查询的 AI 辅助决策数据层是 AI 介入收益高但风险也最大的地方。AI 对 schema 设计的建议基本靠谱因为关系型数据库的建模规则相对成熟但它很容易忽略真实数据量级带来的问题比如忘记给外键加索引、在明细表上做深分页、把需要事务保证的多步操作拆成独立更新。我的处理方式是分层信任schema 设计和迁移脚本生成可以放手让 AI 做但每一条索引、每一个事务边界、每一条大表查询都必须人工确认。SQL 生成这块我通常会给 AI 附上表结构和查询频率说明要求它给出执行计划分析或至少标出潜在的全表扫描。AI 写的迁移脚本还有一个常见毛病直接删列或改列类型生产环境数据会遭殃所以迁移脚本必须走严格的审查流程。4.3 前端组件让人工盯交互让 AI 管构建前端是全栈里最不适合纯 vibe coding 的环节。AI 生成页面布局和组件代码的效率毋庸置疑但它对交互细节的把握经常差一口气弹窗关闭后焦点没有还原、加载失败状态没有提示、极端文案超出容器后布局错乱这类问题在生成时几乎不会被考虑。所以我给前端定的边界是AI 负责把结构和状态管理搭好包括组件拆分、数据请求、基础样式人负责交互细节的评审和修正。实操中我会在提示词里明确要求 AI 生成所有 UI 状态加载、空态、错误态、成功态的代码而不是只写理想路径。这招能堵住大部分看起来没问题一用就露馅的交互 bug。5. 质量护栏AI 代码的测试、审查与回归防线5.1 为什么 AI 生成代码需要更强的自动化测试代码是人类写的人会遵守自己脑子里的隐性约定代码是 AI 生成的AI 没有脑子里的约定它只遵守显式写在上下文里的规则。这意味着 AI 代码在表面正确之外隐藏着大量未经约束的假设而这些假设只有测试能暴露。所以我的原则是AI 生成的每一个功能模块必须同时生成测试没有测试的 AI 代码不允许合入主干。这里的测试不只是覆盖率高而是要有真正的业务断言。AI 很擅长生成顺着实现走的测试那种测试永远能过但永远发现不了 bug。我会要求 AI 基于规格里的验收标准写测试而不是基于它自己写的代码写测试。5.2 可执行规格把验收标准变成自动化断言规格说明书如果不和自动化绑定就只是一堆没人看的文档。我在项目里推行了一种做法把规格里的每一条验收标准映射到至少一个自动化断言。比如注册接口返回参数错误时必须返回 400在规格里写清楚然后在测试代码里对应一条具体用例。这个映射关系的维护也交给 AI 做规格变更后让它扫描出受影响的测试用例并同步更新。这样规格、代码、测试三者保持同源AI 改代码时不会出现功能改了测试没跟上的脱节。我习惯用真实用户路径的端到端测试兜底再配合接口契约测试形成两层护栏。5.3 代码审查清单人工该盯哪些环节即便自动化测试再充足人工审查依然是 AI 全栈开发里不可替代的一环但人工应该盯关键风险而不是逐行读代码。我的审查清单常年保持这几项权限与身份认证边界是否和规格一致数据校验是否覆盖所有入口而不只是前端调用错误处理是否泄露了内部实现细节密钥和敏感配置有没有被打进代码或日志依赖版本是否固定新增依赖是否必要是否引入与现有架构风格不一致的写法。这六项里每一项我都遇到过真实事故。尤其是错误处理泄露内部细节AI 默认会把异常堆栈直接返回给客户端本地开发没感觉上线之后问题详情被所有调用方看得清清楚楚是很典型的安全隐患。6. AI 全栈开发高频事故与完整排查链路6.1 事故一模型幻觉出的 API 在运行时才暴露有一次 AI 生成的代码里调用了某个内部服务的一个看起来存在的接口参数名和响应结构都对得上但翻遍整个代码库和大仓里的定义才发现这个接口根本不存在。这是大模型幻觉在代码生成场景里最典型的表现它对 API 的记忆来自训练数据里的公共代码而不是你项目的真实情况。排查过程很典型功能上线后服务日志里全是 404一开始以为是网关路由问题查了一圈才发现是调用方写错路径。这个问题的根治办法是让 AI 在生成代码前先读取接口定义文件或自动生成的客户端 SDK并且把不允许臆造接口所有外部调用必须在接口目录中可查写进规则文件。6.2 事故二上下文污染导致的幽灵依赖上下文污染是长会话里最容易踩的坑。有一次我在一个已经跑了几十轮对话的会话里让 AI 给项目加一个导出功能它生成的代码里 import 了一个早前讨论过但已经被否决的第三方库。因为那个库的名字在上下文里出现过模型就认为它是可用依赖。这种幽灵依赖特别难排查因为编译时可能通过如果库里恰好有同名导出运行时才在特定路径崩溃。我的对策是会话超过一定轮数或者涉及时效性强的依赖信息就开新会话只带必要的上下文文件。另外每次 AI 引入新依赖时必须在提交说明里高亮标注审查时重点确认。6.3 事故三AI优化引发的性能回退还有一次更隐蔽我让 AI 优化一个查询接口的响应速度它把原来用数据库聚合查询的统计逻辑改成了循环里逐条调数据库查询理由是代码更容易理解。单测全过功能正常但接口响应时间从 300 毫秒涨到了 15 秒。这类性能回退在运行时才暴露而且 AI 不会主动告诉你这次改动的复杂度变高了。我现在要求 AI 在重构类任务里必须附上复杂度分析涉及数据库的必须附上查询次数说明N1 检测并且与改动前的指标做对比。没有这些说明重构类任务一律不接收。6.4 排查链路复现-隔离-反馈-固化的四步法综合这些事故我沉淀了一套固定的排查链路特别适合 AI 生成代码的问题定位复现写最小复现用例明确稳定触发问题的条件隔离二分定位到具体文件、函数、依赖判断问题是 AI 生成导致的还是原有代码冲突反馈把问题代码连同修复期望一起回喂给 AI但要求它先解释根因再给修复方案避免它盲目打补丁固化修复之后把这次事故变成两条资产——一条是回归测试一条是规则文件里的新禁令或检查项。这套链路最有价值的是第四步。AI 开发最怕的不是出 bug而是同一个 bug 换个马甲反复出现。每修一个事故就把经验固化到规则里AI 的犯错边界会越来越窄整个项目会越用越顺手。7. 团队落地 AI 全栈开发最容易被忽视的三个非技术问题7.1 规格和规则要做版本管理很多团队把提示词、规则文件、规格说明散落在个人聊天记录里这等于让工程经验随人流失。我坚持把所有 AI 相关的上下文资产放进 Git 仓库docs/specs放规格AGENTS.md放团队规则提示词模板也入库。这样新成员加入时能快速对齐规则变更也有历史可查。7.2 必须有人当最后一道人肉审查AI 全栈开发流程再成熟也不能让每个人都完全依赖 AI 输出。团队里一定要有人对整体架构和关键技术决策负责这个人不一定逐行看代码但必须审查每个模块的边界约束是否合理、依赖引入是否克制、测试是否覆盖了核心风险。没有这道人肉审查等于让所有乘客都坐一辆没有司机的车。7.3 把团队的隐性偏好变成 AI 的显性知识每个团队都有自己的隐性偏好错误码风格、目录命名、注释习惯、Git 提交信息的格式。这些东西人相处久了自然对齐但 AI 不会自己悟出来。我每周会花一点时间把团队讨论中达成共识的偏好补进规则文件比如新增接口必须在 OpenAPI 里同步登记所有时间字段统一用 UTC 存储。这些偏好沉淀得越多AI 生成的代码就越像我们自己人写的。最后分享一个小技巧给 AI 下任务之前先在文档里写下三句话——这个任务要解决什么问题、绝对不能触碰哪些边界、怎么判断做完了。这套问题-边界-验收的三角结构是我这一年用 AI 做全栈开发重新落地最顺手的习惯。哪怕没有完整的规格文档这三句话加上规则文件里的项目上下文也能把 AI 的输出质量往上拉一大截。