氛围编码vibe coding这个词火起来之后我身边不少团队都短暂体验过那种“爽感”把需求往对话框里一扔AI 噼里啪啦生成几百行代码跑通的一瞬间大家都觉得自己摸到了未来。但这种快乐通常撑不过三个迭代。等需求开始变更、模块开始互相依赖、代码开始没人敢改的时候当初“让 AI 自由发挥”省下的时间会连本带利还回去。这两年我一直在琢磨一件事怎么把这种凭感觉的“氛围编码”变成有图纸、有轨道、有刹车的 AI 原生软件工程而 SDDSpec-Driven Development规范驱动开发加 Harness驾驭工程 AI 的方法与工具体系就是我实践下来最靠谱的答案。这篇内容适合两类人看一类是在团队里推 AI 编程、但发现“提示词越写越长、代码越改越乱”的开发者另一类是已经听说过 vibe coding、想跳过踩坑阶段直接摸到正规打法的技术管理者。我会把 SDD 的规格写法、Harness 的工具链组织方式、从零到一的落地路径以及我实际踩过的坑全部拆开讲透。1. 氛围编码为什么撑不过三个迭代1.1 氛围编码的本质让 AI 替你飞先把这个概念对齐一下。氛围编码最早是 Andrej Karpathy 带火的说法核心姿态是“完全交给感觉”——你只要给 AI 一个自然语言描述它生成代码你看了觉得差不多能跑就收下甚至很多时候你根本不知道它写了什么。这个模式在写一次性脚本、做原型验证、搭个人小工具的时候效率极高我自己也经常这么干。但我后来意识到一个关键问题氛围编码的本质不是“用 AI 写代码”而是“把工程决策权也交给了 AI”。写代码只是软件工程的一个环节前面有需求分析、架构设计后面有测试、评审、交付、运维。你让 AI 把整条链路都接管了等于请了一个手艺很好的临时工但他不看不画图纸、不跟其他工种对齐、也不按验收标准施工。干小活没问题干大楼迟早出事。1.2 失控的三张账单我在团队里观察下来氛围编码失控后通常要还三笔债。第一笔是技术债。AI 生成代码时喜欢“就地取材”项目里已有的工具函数它未必知道常常自己再写一份重复实现。没有统一约束的话同一套逻辑会出现三个版本一个在 utils 里一个藏在组件内部一个直接内联在业务代码里。等你要改公共逻辑的时候才发现根本不知道哪些地方在用。第二笔是上下文债。上下文窗口再大也是有限的AI 聊着聊着就会把前面定的术语、边界、命名约定忘掉。最典型的表现是第一轮它规规矩矩按你的命名规范写第五轮开始冒出完全不一样的名字和风格。你问它为什么它说“根据之前讨论”但那个“之前”已经被它自己覆盖了。第三笔是信任债。这是最致命的。当代码量涨到一定程度团队里没人敢动 AI 写的模块因为不知道改动会影响哪里也没有测试兜底。于是这个模块就成了“黑盒子”只能加功能不能重构最后要么推倒重来要么永久冻结。我见过一个小组AI 两周写完了项目原型但之后的六周都在跟原型里的技术债搏斗进度反而比传统开发更慢。1.3 升级的本质不是不用 AI而是装上工程骨架所以问题不是“该不该让 AI 写代码”而是“在什么约束下让 AI 写代码”。氛围编码像即兴演奏一个人玩很有感觉但一个乐队要合奏就需要乐谱、指挥和排练纪律。SDD 就是那份乐谱——把模糊需求变成 AI 能照着执行的规格图纸Harness 就是指挥和排练纪律——把编码智能体的行为约束在流程、权限和质量门禁之内。这两样东西合起来才是真正意义上的 AI 原生软件工程AI 负责高强度的编码执行人和工程规范负责定义“做什么”和“怎么算对”。下面我分别把这两块的原理和实操方法讲清楚。2. SDD 规范驱动把模糊需求变成可执行图纸2.1 为什么提示词工程不够用很多人以为把 AI 编程做好关键在于写提示词于是拼命研究“咒语”把需求描述得越来越长。但我在实践中发现提示词本质上是一次“对话请求”它是给聊天用的不是给工程用的。对话的特点是即时、有来有回、容易跑题而且每一次对话之间没有强约束——你说过的话 AI 可能会记住也可能记成另一个版本。SDD 的思路完全不同把需求转化成一份进入代码库的规格文档Spec这份文档不是写给 AI 看的“请求”而是双方共同遵守的“契约”。AI 实现的时候对着契约干活人评审的时候对着契约验收测试也对着契约写断言。好处是需求变了改的是契约AI 跑偏了拿契约拉回来代码出问题了先查契约哪一条没满足。人跟 AI 的关系从“聊天”变成了“按合同办事”。这里我多说一句SDD 和传统意义上的“写需求文档”也有区别。传统需求文档往往是给项目经理看的描述很概括“用户要能登录”这种话在传统文档里就算完成。但 SDD 的规格必须细化到机器可校验的程度每一句描述都要能转成测试断言否则你还是把解释权留给了 AI。2.2 一份合格规格文档的四个要素我自己的规格模板一般包含四块行为契约、边界约束、验收标准、技术约束。缺一不可。行为契约回答“做什么”。要描述得具体到输入输出级别。比如同样是“用户登录”不是写“用户要能登录”而是写“用户输入手机号和密码校验通过后返回 token 和用户信息token 有效期 24 小时”。边界约束回答“不做什么”。这一条很多人忽略但恰恰是 AI 跑偏的重灾区。要明确写“本次不实现注册和找回密码”“不允许修改用户表结构”“不改动第三方支付模块”。AI 的默认倾向是“顺手多做一点”没有边界约束它会主动帮你加功能、改模块最后 diff 大得没法 review。验收标准回答“怎么算完成”。我强烈建议用 Given-When-Then 的格式写每条验收标准都对应一个可执行的测试场景。比如“Given 用户输入错误密码When 提交登录Then 返回 401 且日志不打印密码字段”。这种写法的好处是验收标准可以直接翻译成自动化测试用例AI 做完之后用这些用例一跑就知道合不合格不靠感觉判断。技术约束回答“用哪层、动哪层”。指定允许修改的文件范围、必须遵循的既有接口、不能引入的依赖等。这等于提前给 AI 画了施工红线避免它把不该碰的地基给挖了。2.3 规格拆分的实操手法规格不是一份写完就完事而是要拆到合适的粒度。我习惯按“用户故事 → 任务卡 → 验收清单”三级来拆。一个用户故事包含完整的业务价值比如“用户可以登录”“用户可以找回密码”往下拆成任务卡每个任务卡控制在 AI 能在一次会话内完成的体量我通常控制在 100 到 200 行代码的改动量太大了上下文会飘太小了频繁切换又浪费。还有一个反直觉但很有效的做法让 AI 反过来帮你起草规格。你给它一个粗需求它生成一份初步的规格草案然后人来 review 和修改。这比从白纸开始写快得多而且 AI 往往能补出你没想到的边界场景。但注意规格的最终解释权必须留给人AI 起草的规格如果没人审核就生效等于把需求的事也外包了出去又回到了失控状态。我把这条写进团队规范里AI 写的规格必须经过人工 review和代码 review 同等重要。3. Harness 驾驭工程 AI给智能体装上轨道和刹车3.1 Harness 到底是什么SDD 解决了“做什么”的问题接下来要解决的是“怎么保证 AI 按着做”——这就是 Harness 的战场。Harness 这个词的本意是“挽具”给马套上挽具它才能拉着车走正道。在 AI 软件工程语境里Harness 指一套把编码智能体约束在流程、权限、质量门禁之内的工程体系不只是某一个工具而是“工具 流程 治理规则”的组合。我对 Harness 的理解分三层。第一层是工具层就是实际驱动 AI 干活的 CLI、IDE 插件和工作流配置比如社区里常提到的 Claude Code、CodeBuddy、DeepSeek Harness 这类编码智能体或基于它们封装的工作流插件。第二层是流程层定义 AI 干活时经过哪些阶段、在哪些节点必须停下来等人确认。第三层是治理层把团队的编码规范、架构约束、安全红线以规则文件的形式注入让 AI 在每次生成代码时都能感知到这些约束。3.2 工作流与工具的组织方式工具选型上我不建议一开始就追求“全家桶”。我自己落地时的思路是主智能体负责理解规格和生成代码选择你团队用得最顺手的编码智能体即可在这个基础上用 Harness 工作流把过程切成固定阶段。一个最小可用的工作流长这样第一步规格解析。工作流读取代码库里的规格文档把验收标准提取出来。第二步任务分解把规格拆成原子任务按依赖顺序排队。第三步分步实现AI 一次只做一个任务每个任务做完立刻停下来。第四步自动校验跑预置的测试和静态检查这步不需要人介入。第五步人工确认。这是整个流程里最重要的节点AI 必须停下来说明“我改了哪些文件、为什么这么改、测试结果如何”人确认后才会放行到下一步。第六步回归验证全部任务完成后跑一遍全量回归保证没有互相破坏。这套流程最大的价值是“过程可观测”。氛围编码的问题在于 AI 一步到位写完一大坨中间发生了什么没人知道。Harness 把过程切成有透明度的节点之后每次偏差都能被及早发现而不是等代码合入才发现方向全错了。3.3 权限与回滚刹车怎么装光有流程没有权限约束Harness 也只是个花架子。我建议至少装上三样“刹车装置”。第一是文件白名单和黑名单。在配置里明确指定智能体可以读写哪些目录、禁止触碰哪些目录。比如核心支付模块、数据库迁移脚本默认进黑名单除非任务显式关联才能放开。别小看这一步AI 一旦上下文漂移最容易干的事就是顺手改掉它“觉得”有关的文件白名单能把破坏半径控制在可接受范围。第二是只读模式与编辑模式的切换。很多编码智能体支持把工作区切成只读来解读代码、分析问题真正要改动时再切回编辑模式。我要求团队在方案设计阶段强制用只读模式让 AI 先给出改动方案人批准后再授予编辑权限。相当于看诊和开药分开不能一个医生边看边乱开方。第三是分支策略和回滚点。我给 AI 的每个任务开独立分支任务开始前打基线 tag每一步修改都以 diff 形式记录下来。一旦发现改动失控直接丢弃这个分支回到基线重新来而不是在混乱的 diff 里试图手动修复。这个习惯救过我好几次尤其是 AI 自作主张做“顺手重构”的时候回滚比争论快得多。4. 落地实操一条可复制的升级路径4.1 选项目别拿核心系统练手从氛围编码切换到 SDD Harness最大的误区是第一天就拿核心业务系统当试验田。我曾经在一个流量很高的老模块上试点结果规格还没写完团队就被线上问题拖走了试点不了了之。后来我总结出一个选型标准边界清晰、有基础测试、可独立部署、非核心交易链路。内部工具、数据分析模块、中台的非关键服务都是很好的试点对象。选好项目之后第一个任务不是写功能而是把现有代码的测试框架补齐。SDD 和 Harness 的底层逻辑都是“先有验收标准再干活”而验收标准必须落到测试上。没有测试兜底AI 做出来的东西到底对不对全靠人肉看效率优势根本发挥不出来。这一步不做完后面全是空中楼阁。4.2 搭建规格到实现到验证的闭环具体落地时我遵循一套五步闭环每一步都有明确的产物。第一步把需求翻成规格文档结构就是我上面说的四个要素完成后团队做一次规格评审。第二步根据验收标准写自动化测试这个环节我坚持“测试先于实现”让测试先红起来形成一个可以量化进度的基线。第三步把规格文档交给 Harness 工作流让 AI 按规格实现过程中只允许碰白名单里的文件。第四步跑测试加人工 review测试全部变绿只是最低标准review 时重点看改动是否超出规格范围。第五步把实现过程中发现的规格缺陷记录下来回流到规格文档里更新后再进入下一轮。这里有一个必须强调的点给 AI 设时间盒。AI 在实现过程中陷入死循环是很常见的事尤其是它反复改测试去迎合自己的实现或者在一个小问题上自我纠缠。我的做法是单任务限制若干次尝试超过就停止由人介入判断是规格问题还是实现问题。这个机制避免了“AI 自嗨式轮回”实测下来能省掉大量无效等待。4.3 沉淀团队资产从个人技巧到组织能力这套方法论跑通一个项目之后最值得做的一件事是把过程中的资产沉淀下来而不是停留在“某个高手会配置”的状态。我把沉淀分成四类全部放进团队仓库。第一类是规格模板库把我常用的行为契约、边界约束、验收标准的写法固化成模板新项目直接套。第二类是 Harness 工作流配置和命令文档包括工具怎么装、插件怎么配、确认点怎么设确保团队成员能自行复现而不是依赖某个人的电脑。第三类是失败案例库记录每一次 AI 跑偏的典型模式比如“忽略边界约束擅自扩展了文件白名单”“把验收标准里的 Given 场景理解歪了”这些案例比任何规范文档都更有说服力。第四类是质量门禁脚本把静态检查、单测覆盖率、关键路径测试固化成脚本AI 每次提交都自动跑一遍。这一步完成后团队对 AI 的态度会有一个明显转变从“AI 写的代码我不敢信”变成“AI 写的代码有流程兜底我可以把精力放在它做不好的事上”。我认为这才是 AI 原生软件工程的真正形态不是人围着 AI 转而是 AI 融进人的工程体系变成一个受控的执行单元。5. 常见问题与排查实录5.1 规格写了跟没写一样这是我最常被问到的现象明明给了 AI 一份看起来挺详细的规格它还是自由发挥。排查下来多数情况不是 AI 不听话而是规格里的验收标准写得“不可测”。比如写“登录体验要好”这种话AI 只能靠猜。破解方法是把每条验收标准改写成 Given-When-Then 格式并且要求能直接翻译成断言。给 AI 一句“密码错误时返回友好提示”它容易给你写一堆弹窗和文案给 AI 一句“Given 错误密码When 提交Then HTTP 状态码为 401 且响应体包含错误码 10023”它就只有一个明确动作了。5.2 AI 改一处坏一片另一个高频问题是小需求被 AI 改成了大重构。我见过一个案例需求只是给列表页加个排序参数AI 顺手把底层的数据查询逻辑重写了理由是“发现旧实现有性能隐患”。听起来很合理但实际上换了查询方式之后依赖旧逻辑的另外三个页面全出了兼容问题。这类问题的根源是缺少“改动范围”约束AI 有自主优化倾向但这在交付链路里是越权行为。对策就是我上面说的文件白名单加改动面检查任务完成后第一步就看 diff 涉及的文件是否在预设范围内不在就立刻回滚不用给 AI 解释的机会。5.3 插件加载失败、工作流不启动聊点更实操的。社区里这类工具的安装和使用经常出“failed to load plugins”“web boot 阶段报错”之类的问题我也踩过不少。这类问题九成是环境层面的跟 AI 能力无关按下面几步排查基本能解决。第一步核对版本对应关系。智能体主程序、工作流插件、运行时配置往往是分开发布的版本不匹配是最常见的原因先把三者的版本号对齐到文档推荐的组合。第二步看启动日志的关键字。日志里出现 plugin、boot、activate 这类词时重点看它具体是哪个插件没被激活以及激活失败的原因是什么多半会附带一个错误码或路径信息。第三步检查配置文件的路径和权限。很多人把配置放在带中文的路径下或者目录缺少读写权限插件扫描不到自然就加载失败挪到纯英文路径并把权限放开通常就好了。第四步注意依赖完整性这类工作流往往依赖固定的运行时版本缺了底层依赖插件启动时会默默失败装齐依赖再重启。5.4 避坑速查表最后把我实践过程中高频遇到的坑整理成一张速查表方便你在现场快速对照。现象常见原因处置方式插件服务启动失败版本组合不匹配或缺少运行时依赖对齐版本组合补齐依赖后重启并看 boot 日志工作流不按规格执行没有把规格文档显式挂载给工作流在流程配置里指定规格文件路径启动时先做规格解析校验AI 改动范围失控缺少白名单与只读模式约束配置目录白名单方案阶段强制只读测试被 AI 改到全绿测试和实现由同一智能体在无监督下修改将测试文件设为只读或要求测试变更必须人审上下文越聊越飘单任务体量过大超出上下文有效范围拆小任务每完成一段就做一次确认与基线记录验收标准无法落地规格写得过于模糊无法转成断言用 Given-When-Then 重写验收标准这张表里的每一条都是真实发生的场景不是理论推演。尤其是“测试被 AI 改到全绿”那条很多人一开始根本想不到会发生但一旦发生前面的验收闭环就形同虚设所以我把测试文件单独设成只读从机制上杜绝。我个人在实际操作中的体会是SDD 和 Harness 说到底是两件事把需求说清楚把过程看住。工具一直在变今天你用这个智能体明天那个插件发布新版本但这两条原则从来没变过。如果你是刚准备切换建议不要一次性铺开挑一个小模块把规格写完、门禁配上、工作流跑通一次让团队亲眼看到“AI 在约束下干活”和“AI 自由发挥”之间的差别后面推进就顺了。最后再分享一个小技巧把规格文档放进代码库纳入 review 流程让 AI 的每一次提交都能追溯到规格的某一条验收标准——这一个动作比配置任何复杂的工具都管用。