做完这个项目我最大的感受就是AI全栈开发真正难的从来不是让AI写出代码而是让AI在二十个功能模块、三千次会话之后仍然沿着最初的需求主线往前走不跑偏、不返工、不失控。这一路踩下来真正管用的不是某个大模型有多聪明而是两样东西——SDD规范驱动以及Harness工程驾驭。这个系列写到这里是最后一篇了我把从理念到落地的完整链路连同那些坑和取舍一次性说清楚。1. 先看清问题AI全栈开发真正缺的不是能力是控制面先聊一个反直觉的结论我见过很多团队上AI全栈开发第一周都兴奋得不行觉得提效好几倍。但做到第二个月几乎无一例外开始头疼——代码量越堆越多系统却越来越难维护AI改一个bug会带出三个新bug功能逻辑互相打架接口签名说变就变测试报告一片绿但生产环境照样出问题。问题出在哪里不是模型不行而是整套开发过程缺少一个控制面。1.1 失控的三个典型表现我把这段时间观察到的失控现象归纳成三类每一类都是真实的项目事故来源。第一个是需求漂移。对话式AI开发有个天然毛病上下文会漂移。你和Agent聊了四十轮需求一开始说给用户发通知聊到后面变成了给用户发带附件的多渠道通知再聊几轮变成还要做退订管理。每一步单独看都没错但最后代码库里的东西跟最初的设计意图已经完全不是一回事。在没有规范约束的情况下AI会忠实地跟着你最后一句话走而不是跟着最初的目标走。第二个是隐性依赖污染。Agent为了完成当前任务经常自作主张引入新依赖、新工具、新抽象。比如为了做一个时间格式化顺手装了一个第三方库为了省事把某个公共函数的签名改了。这些动作单看都对但它们打破了其他模块对原有实现的心智预期。最麻烦的是这些问题不会在编译期暴露只会在某个深夜上线的瞬间炸给你看。第三个是上下文膨胀造成的视野变窄。项目代码量过了几万行之后任何单一会话都不可能装下全部上下文。Agent只能在它看得见的局部做决策而局部最优拼在一起往往不是全局最优。没有机制告诉它这个模块的边界在哪里哪些文件是相关约束、哪些可以不管它就会像修剪灌木一样每个枝条都剪得很齐整但整棵树却变形了。1.2 结论开发的方向控制和过程控制必须外置我后来想明白一件事人类工程师能在大项目里不翻车靠的是纪律、规范和设计评审不是靠记忆力。AI比人类记忆力强得多但它同样需要纪律、规范和评审机制甚至比人类更需要——因为人类对自己的无知有感知AI没有。所以整个系列的核心主张就是这个把开发的方向控制交给SDD规范驱动开发让所有开发和演进都围绕一份结构化契约展开把开发的过程控制交给Harness工程驾驭让每一次AI的产出都经过校验、检查和回退的闭环。两者加起来才是完整的AI全栈开发方法论。一句话概括这套思路SDD管做什么、什么叫做好Harness管怎么做、做坏了怎么办。2. SDD规范驱动不是写需求文档是把需求编译成AI能执行的契约很多人一听到规范驱动就以为是要写更多文档。恰恰相反。我给团队定的规矩是宁可删掉需求文档也要保住规范文件。这两个东西的本质区别非常大。需求文档是给人读的里面充满了背景故事、术语解释、业务场景描述甚至还有情绪铺垫。而规范文件是给AI执行系统读的它必须结构清晰、颗粒度统一、每条都可验证。传统需求文档AI读不懂不是因为它不能理解自然语言而是因为自然语言里充满模糊量词和隐含条件。比如系统要在高并发下保持稳定这句话人和AI都看懂了但它没法被验证而接口在500TPS压力下P99响应时间低于800毫秒错误率低于0.1%持续压测30分钟无内存持续增长这就是可验证的规范。2.1 需求文档和SDD规范的本质区别我做了个对比这里直接列出核心差异看完就明白为什么要重写一遍规范文件而不是直接扔需求文档给AI维度传统需求文档SDD规范文件读者人人和AI执行系统结构叙述性、按业务背景组织条目化、按可验证单元组织验收标准尽可能保证合理明确指标、明确断言、明确边界接口定义散落在各处集中定义带类型和取值范围变更管理靠口头沟通走版本号、走变更记录2.2 好的SDD规范长什么样我需要讲清楚一个可复用的规范文件模板这是这一篇里最值得抄作业的部分。一个完整的SDD规范我习惯分成六个区块区块一模块身份卡。功能编号、模块名称、版本号、依赖的上下游模块。比如NOT-001 用户消息通知中心 v3.2依赖用户服务USER-SVC、模板服务TPL-SVC。别小看这一栏它是后续Harness做影响范围分析的基础——Agent改代码之前先看依赖知道哪些模块会被波及。区块二接口契约。所有对外暴露的函数、API、事件、数据结构必须写明输入参数类型、输出类型、取值范围、异常类型。格式直接用Interface Definition风格就算不用IDL工具也要用表格列清楚。原则是接口定义只描述是什么不描述怎么实现。区块三业务规则。每一条规则编号化、可单测化。比如规则R-101同一接收人在5分钟内最多收到3条同类型通知超过则合并为一条摘要通知。规则不允许写如果用户没有设置偏好给一个合理的默认值这种话必须写明默认值是什么。区块四验收标准。这是SDD里最重要的区块。我要求每一条验收标准必须能映射到一个自动化测试断言。比如A-301单元测试覆盖发送接口的分支新建用例时Mock HTTP下游断言超时分支返回RETRYABLE_ERROR。宁可多写十条测试断言也不要写一段系统应正确处理异常情况。区块五边界条件和异常处理。把你能想到的所有异常输入、异常状态、极端情况列出来要求Agent在实现时必须显式处理。比如数据库连接失败、下游超时、消息体超长、渠道黑名单等。这一块是防止AI代码表面正确的关键。区块六非功能要求。性能、可观测性、安全约束。不需要贪多抓到当前最重要的两三条就行。比如发送接口必须在日志中记录request_id所有第三方调用必须带超时和熔断配置。2.3 从规范到任务分解拆解规则是SDD落地的关键动作规范文件本身不直接生代码它要先被拆成Task序列。拆分的过程我有几条硬性经验第一每个Task必须对应规范里的一个可验证单元一个Task做完了对应的验收断言必须能独立跑起来。第二接口定义先行、实现后置。也就是说Agent必须先输出接口契约审过接口再写内部实现这样多模块并行时不打架。第三每个Task的产物边界必须明确任务结束后可以新增哪些文件、可以修改哪些文件、绝不能碰哪些文件。我一开始犯过的错误是拆任务拆得太粗一个Task让AI实现消息通知模块结果它一口气写了两千行代码检查的时候根本没法定位问题。后来改了规则单个Task的产出代码量控制在两三百行以内超过就得继续拆。这不是死规矩是因为AI在长上下文里保持一致性会衰退短Task的成功率高很多。2.4 实操模板我的SDD最小可用模板这里直接给一个我目前项目里在用的精简模板你们可以拿去改。用中英夹杂没关系关键是结构别丢module: id: NOT-001 name: user_notification_center version: 3.2.0 depends_on: [USER-SVC, TPL-SVC, CHANNEL-SMTP, CHANNEL-NOTIFY] interfaces: - name: send_notification request: channel: enum[email, inapp, webhook] receiver: string(128) template_id: string(64) params: mapstring, any request_id: string(uuid) response: message_id: string status: enum[queued, sent, failed] errors: [INVALID_PARAM, TEMPLATE_NOT_FOUND, CHANNEL_UNAVAILABLE, RATE_LIMITED] business_rules: - id: R-101 desc: same receiver same template within 5min merge into digest assert: count(notification_event) 3 per receiver per template per 5min - id: R-102 desc: webhook channel must retry up to 3 times with backoff 1s/4s/16s assert: retry_count 3 and retry_interval matches spec acceptance: - id: A-301 desc: unit test covers timeout branch and returns RETRYABLE_ERROR - id: A-302 desc: integration test with mock SMTP asserts email is sent with correct payload - id: A-303 desc: 500TPS load test P99 800ms, error rate 0.1%, 30min no leak写完这份规范AI要做的不是猜你的意图而是严格按照每一条去实现、去测试。规范的每一条规则都是可执行的断言什么叫完成就变成了一个布尔值——测试全过的布尔值。这是SDD核心价值。3. Harness工程驾驭不是提示词工程是给Agent装方向盘、刹车和仪表盘SDD解决了方向问题但光有方向还不够。就像一辆车有导航但没方向盘和刹车你只能看着它冲向路边。落地过程中真正把SDD的威力释放出来的是外面这层Harness——工程驾驭框架。3.1 Harness到底是个什么东西先破除一个误解Harness不是一段更聪明的系统提示词也不是某个IDE插件。它是一整套围绕Agent工作流的可执行控制层包括任务调度、上下文裁剪、工具调用约束、检查点、回退机制、状态记录和人工介入接口。打个比方大模型是发动机SDD是导航路线Harness是整辆车的控制系统——它决定什么时候给油、什么时候刹车、什么时候转弯、仪表盘报警了怎么处理。没有这层控制再强的发动机也只是怠速轰鸣的野兽。在具体落地的时候Harness可以是独立脚本可以是基于Claude Code或CodeBuddy这类工具的配置层也可以是自己写的Agent调度器。社区里常说的deepseek harness这类工作流插件本质就是这个思路——给模型配一个工程框架让它在边界内干活。具体用哪个壳不重要控制层的机制才重要。3.2 三层驾驭结构执行层、检查层、回退层我实践下来一个可靠的Harness至少要有三个层次缺一层都会出问题。第一层是执行层负责把SDD任务拆成Agent可执行的子任务序列调度模型的调用管理上下文窗口。这里有个容易被忽视的点上下文边界管理。每个Task执行时执行层只把与该Task相关的接口定义、涉及的文件列表、约束规则喂给模型其余一律不给。模型每轮能看到的内容是最小作用域的就像函数式编程里的局部变量它改不到全局的东西。很多Agent越改越乱就是因为上下文给了全局代码库它觉得自己什么都该碰。第二层是检查层在Agent每完成一个子任务产物后立即运行。检查内容至少包括静态编译、单元测试、规范符合度扫描、变更影响范围核对。规范符合度扫描是SDD和Harness咬合的关键——用脚本把SDD里的验收断言映射成具体的检查命令跑不过就返回失败不会因为Agent声称完成就放行。我见过很多团队在这里偷懒只看编译通过就收工结果业务规则全错。第三层是回退层检查不通过时的处理策略。不是简单地让模型重试一次而是分级处理小问题格式错误、命名不规范直接进自动修复循环中等问题某个测试跑不过把失败日志、相关代码段、测试输出重新塞回给Agent让它针对失败点修复大问题跨模块接口不一致、验收断言大面积失败要停下来回到SDD层面确认是规范写错了还是实现写错了修正之后再重跑任务。3.3 工具调用约束与环境隔离这一块是Harness控制面里最容易被新手跳过、又最容易出事的部分。AI Agent在开发过程中会调用各种工具执行命令、读写文件、调数据库、发网络请求。如果不加约束它一个顺手就能把生产环境配置改了或者把测试库数据洗了。我的原则是白名单机制加沙箱运行。白名单列出Agent允许触达的工具和命令文件读写限定在工作区内、命令限定在构建和测试相关指令、网络访问默认阻断。沙箱是另一个关键所有Agent生成的代码在独立的Docker容器里跑测试容器里打快照跑坏了整个环境直接回滚重来。这套机制保证了AI做错了没事最坏情况回到上一个检查点而不是AI做错了带着生产环境一起遭殃。还有个看起来琐碎但非常重要的事情依赖锁定。AI为了省事容易引入新库白名单机制里要加一道依赖审查——新增依赖必须走人工审批。我经历过一次事故Agent引入了一个字符串处理库结果这个库的版本跟核心框架冲突上线当天疯狂抛异常。从那以后新增依赖默认禁止只有人工显式放行才允许。3.4 与主流AI编程工具的配合方式我实际工作中用过几套组合这里把配合逻辑讲清楚。基于Claude Code这类交互式工具的Harness主要表现形式是hook脚本和自定义规则文件。工具负责Agent和代码库的交互Harness在关键节点拦截产物、跑检查。比如在每次Agent修改完成后触发一个钩子自动跑规范扫描器不过就让Agent继续改。这套方案优点是上手快缺点是检查逻辑全散落在各种脚本里维护成本会起来。做完整的项目我建议自己写一个调度器把模型调用、工具链、检查脚本全部收进来。CodeBuddy这类IDE里也可以嵌入脚本但更常见的是独立进程。我自己的落地路径是先以工具插件方式跑通局部验证了SDD规范的质量再逐步把检查逻辑收拢成独立Harness核心。社区里deepseek harness这类自定义工作流方案走的就是这条路径——在模型之上叠规则、叠检查、叠回退。3.5 本地配置Harness的常见报错与处理配置Harness时我踩过一个很典型的坑就是插件清单和运行时版本不匹配导致的加载失败。表现形式往往是控制台报类似failed to load plugins、web boot: entries did not activate这样的错误。排查路径很有代表性第一步先看插件清单文件的格式和路径很多加载失败都是路径写错或清单格式不符合要求。第二步看运行时日志里具体哪个entry没激活把不激活的三个常见原因过一遍依赖的服务没起来、版本号与当前运行环境不兼容、清单里声明的钩子函数在代码里找不到。第三步如果是版本不匹配优先锁定运行环境版本再调插件声明不要反过来先升级环境。这种加载失败先查清单再查依赖最后查版本的思路实际上就是最简单的Harness排查方法论。把这套逻辑内化成肌肉记忆之后后续遇到更复杂的Agent工作流异常都能快速定位。4. 实战拆解一个消息通知模块从SDD规范到全栈交付的完整链路方法论说再多不如一个完整案例来得实在。这里我用一个简化过但保留了关键细节的真实模块做样例带大家走一遍整个流程从写规范、拆任务、跑Harness到一次真实的检查层拦截和回退。4.1 需求场景和SDD规范编写假设要做一个用户消息通知中心支持邮件、站内信、Webhook三种渠道。需求方给的原始描述就一句话用户触发某个操作时系统要给相关人发通知注意别发太多别把用户烦死了。这句话当然不能直接扔给AI。我把它改写成SDD规范核心内容就是前面章节里的那个模板。业务规则上别发太多转成了一条可测试的限频规则同一接收人在5分钟内最多收到3条同类型通知超出则合并成摘要。这是从模糊需求到可验证断言的关键一步。接口契约部分我把send_notification接口的入参、出参、错误类型全部定义清楚。注意这里每个错误类型都有明确触发条件Agent编码时不用猜。验收标准部分我写了三类单测覆盖关键分支、集成测试用Mock Mail Server验证邮件投递、压测验证性能指标。4.2 Harness执行路径任务序列与检查点规范写好后Harness开始工作。我设计的Task序列如下Task1负责初始化项目骨架、建数据库迁移脚本。检查点是迁移脚本dry-run通过、权限校验通过。Task2负责实现send_notification核心接口。检查点是编译通过、针对R-101限频规则的单元测试通过。Task3负责Webhook发送回调与重试逻辑。检查点是重试时序测试通过。Task4负责接入三种渠道的适配器。检查点是集成测试用例全部跑过。每个Task执行时Harness只把这个Task对应的接口定义、涉及的文件列表和约束喂给模型。模型每完成一个Task检查层自动跑一遍对应的测试和控制脚本不通过就进回退层。4.3 真实事故复盘连接池泄漏是怎么在检查层被拦下来的这里讲一个让我印象极深的真实案例。Task2完成时编译和单测全绿看起来一切正常。但检查层里有一道连接泄漏检测跑集成测试的时候监控进程的数据库连接数。第一次跑完连接池里的连接数比预期多了十几个。直觉告诉我这是泄漏——Agent在某个异常分支里获取了连接但没有归还。但更值得记录的是回退层的第一轮处理。Harness把连接数异常的报告、相关代码段一起塞回给Agent让它修复。Agent确实改了但改完又引出一个新问题它在某处提前关闭了连接导致后面一个事务报错。检查层的测试立刻把它拦住了。这就是回退层的好处——Agent可以错一次、错两次但错误的代价被限制在一个Task范围内不会扩散到整个项目。第二轮我再仔细看了代码发现问题根源不只是忘了归还连接还有一处异常处理路径里把defer写在了错误位置导致异常时资源释放代码根本没执行。我意识到这类资源生命周期问题靠Agent自我修正效率不高于是在SDD规范里加了一条代码约束所有数据库连接获取必须使用统一的连接管理器禁止裸调连接。规则更新后重新跑Task2一次通过。这个案例给我的启示是回退层不是无限重试当同一个Task连续回退两次就应该怀疑SDD规范本身有盲区补规则比继续让Agent试错更有效。4.4 交付结果与验收复盘整个模块做完用了四个Task、三次回退、一次规范补全耗时一个下午。如果纯粹让AI放开了写可能两个小时就写完了但后续排查问题可能要花两天。有了SDD和Harness大部分问题在Task边界内就被拦截了交付后我只需要做最终的代码走读和性能验收。最终验收时500TPS压测过了P99约700毫秒连接数平稳。限频规则用脚本灌了十万条事件验证合并逻辑正确。这个模块上线后跑了一个月没有因为这个模块本身的逻辑出过一次事故。可以说这是一个稳稳当当的AI全栈交付样本。5. 多AI协作时代的Harness多Agent并行、争议裁决与RPA落地单Agent跑通一件事不难真正考验Harness能力的是多Agent协同。我现在做项目不是让一个AI干所有活而是让好几个Agent并行各管一摊。刚开始这么干的时候很混乱后来总结出一套可行的方法。5.1 多Agent各说各话的问题与解法三个Agent并行的时候如果互相之间没有契约就会出现典型的各说各话A模块的Agent定义了一个UserId字段类型B模块的Agent用了UserID字符串C模块的Agent直接拍脑袋用了userId: Long。每个模块单测都过联调时全崩。解法其实SDD里已经定了接口契约阶段的输出就是协议所有Agent都必须遵守。Harness在任务调度时强制每个Agent先读到统一接口契约不允许任何人私自改。如果必须变更走版本升级流程变更之后所有依赖模块的测试都要重跑。5.2 主从式Agent架构和职责边界我的多Agent配置通常是这样的架构一个主控AgentOrchestrator负责任务分解、进度跟踪、最终验收它不直接写业务代码。多个开发AgentWorker分别负责不同模块只接收主控下发的Task和对应的规范片段。一个代码评审Agent负责挑刺专职看代码质量、潜在bug、规范偏离。一个测试Agent负责根据规范生成测试用例补充Harness检查层覆盖不到的场景。一个文档Agent负责维护SDD规范的状态和变更记录。这个架构最大的好处是职责单一。评审Agent不用写代码它不会维护自己写的代码而心软测试Agent不用实现功能它专门想办法把实现搞坏——这两个角度分开之后整体质量比单Agent代码自测高出很多。5.3 状态标记与仲裁机制多Agent协作必须有个统一的状态视图。我要求所有Task在Harness里显式标记状态pending/in_progress/done/failed/needs_review。状态变化由Harness统一管理Agent不能自己把自己标记为完成必须通过检查层验证后才转done。仲裁机制是另一个容易被忽略的部分。两个开发Agent对同一个公共接口的实现方案有分歧时我们不能指望AI之间自己谈拢。我的做法是争议先升级给主控Agent主控对照SDD规范作出裁决如果SDD规范里也没写清楚就开一次人机评审会由我把规则补进规范再继续。简单说AI之间的分歧永远不要在代码层面解决一定要回到规范层面解决。5.4 Harness思路在RPA落地中的延伸多AI协作这套东西我后来发现直接可以用在RPA机器人流程自动化落地项目里。以前做RPA每个机器人脚本各写各的流程一多就互相踩脚数据格式不统一状态还不可追踪。用了Harness的思路之后每个RPA机器人被视为一个Agent每个自动化流程先写一份流程SDD——明确输入、输出、异常处理、数据格式、验收断言然后由一个调度管理器来编排机器人之间的依赖和状态。实践下来最直观的变化是两个第一机器人之间的数据交接不再靠约定俗成而是靠契约文档和运行时校验第二某个流程失败后的重试策略和影响范围被清晰管控一个机器人挂掉不会拖垮整条链路。这套跨领域的方法迁移是我在这个系列里最意外的收获。6. 连载至此的边界认知SDD和Harness到底管什么、不管什么写了这么多篇到这篇收尾我觉得有必要把边界也讲透。任何方法论都有适用边界SDD和Harness不是万灵药搞清它们的边界反而能让它们用得更准。6.1 SDD会失效的场景探索型需求当需求本身处于探索阶段连你自己都不知道什么叫对的时候SDD的强行规范会起反作用。比如做一个新的UI视觉风格、探索一个全新的交互模式这类任务的核心价值在于试错和发散你如果先写一堆验收断言反而把AI的手脚捆死了。我的建议是分阶段处理探索阶段用非正式对话原型验证的方式让AI自由发挥跑通一个粗糙雏形评估方向一旦方向确认立刻把探索结论固化成SDD规范再进入正式的开发阶段。先发散、后收敛比全程发散或全程收敛都高效。6.2 Harness误伤管太死导致Agent能力萎缩约束太轻会失控约束太重也会有问题。我有段时间在Harness检查层加了非常多的规则结果发现Agent变得极度保守每次改动都只做最小变更宁可重复代码也不肯抽取公共函数因为怕碰了别的模块引发检查失败。后来我调整了策略把检查规则分成硬性门禁和软性建议两类。硬性门禁必须通过——测试、编译、安全扫描软性建议供参考——代码风格、命名规范。同时定期做松绑实验随机放宽某些约束让Agent发挥创造力看看有没有带来意外的好方案有就吸收到规范里没有就恢复约束。6.3 对AI测试开发方向的延伸思考最后聊聊热词里提到的AI测试开发。现在我越来越觉得SDD规范驱动在测试领域价值更大——因为测试本身就是为规范服务的。AI测试开发的正确路径不是让AI随机生成一堆测试用例而是让它从一个模块的SDD规范出发针对每一条业务规则、每一个边界条件、每一个验收标准去设计能够证明代码满足规范的测试策略和测试用例。这套方法论完全可以复刻过来。6.4 写在最后的一点体会这个系列到这里收尾了。我记得最开始做AI全栈开发的时候被那种AI一口气写好几千行代码的爽感冲昏过头。后来经历了几次线上事故才意识到工程化的核心不是让AI多快而是让它出错之后的代价多小。SDD和Harness给我的最大改变不是交付更快而是睡得安稳——该有的验收跑过了再上线该收敛的边界有人盯着该回退的时候一步退到干净的地方。如果你正在做AI全栈开发的落地我真心建议不要急着堆更多更好的模型先把规范文件的结构定下来先让每个Agent的产出有明确的验收断言先让每次失败都有低成本的回退机制。做到这三点哪怕用最普通的模型整个项目的可控性也会上一个台阶。反过来这三样缺一样换再强的模型也只是把跑偏的速度提得更快而已。