这半年我几乎把主力开发环境切到了AI辅助模式结果发现一个特别拧巴的事生成速度是真快代码也是真敢写。一个接口能给你造出五种风格测试用例看着能跑一改就碎。团队里开始有声音说AI写代码不如人写但我清楚问题不在模型而在我们太把AI当“人”用了既没给规矩也没上缰绳。后来我搭了一套基于SDD规范驱动 Harness驾驭工程AI的辅助开发体系。这套体系的核心就一句话用规范约束AI“做什么、做成什么样”用Harness管控整个流程让每一段生成代码都可控、可审、可回退。这篇文章不讲空泛概念只讲我实际落地的架构、配置和踩坑记录。适合正在被AI代码质量折磨的技术负责人以及想给团队上一套可控开发流程的开发者。如果你还在“让AI自由发挥”阶段大概率会在这里看到很多熟悉的痛点。1. 为什么需要“规范驾驭”体系失控的AI代码是常态1.1 失控的AI代码问题不在模型在缺少约束先说一个我观察到的现象很多团队引入AI编程之后第一个月效率确实暴涨第二个月就开始出现“AI产出物堆积没人敢合并”的情况。原因很简单模型大概率生成语法正确、逻辑不确定的东西它不知道团队的业务边界也不知道哪些约定是不可破坏的。举个例子我见过一次AI自动生成用户注册接口它为了让“唯一性校验”看起来更酷自己加了一个分布式锁。代码能编译单测也过了但它把Redis引入到了一个原本不需要Redis的模块。如果没有人review出来这个依赖会像慢性病一样扩散。类似的问题还有风格漂移、重复造轮子、吞异常、绕过校验逻辑去迎合测试。这些问题不是靠调一个更强模型能解决的本质上是因为我们没有给模型一份“不可逾越的合同”也没人盯着它执行过程。所以我后来不再纠结“哪个模型写代码最强”而是把精力放到“如何让任意模型都在框架里干活”。AI代码失控不可怕可怕的是失控之后没有任何机制发现和回退。这也是我需要SDD和Harness的根本原因。1.2 SDD规范驱动把“消灭模糊”当第一目标SDD全称是Specification-Driven Development规范驱动开发。它不是什么新鲜概念传统软件工程里就有人强调先写规格再写代码。但在AI辅助开发这个场景下它的意义被放大了无数倍。因为人看模糊需求会自己脑补AI也会脑补而且脑补得更自信。我的理解是SDD的本质是把“需求、约束、验收标准”固化成一份结构化的、机器可读的文档让AI在动手前就知道目标是什么、允许做什么、禁止做什么、怎样算完成。这就像你请外包团队干活除了聊个大概还必须签一份验收清单不然对方交付时一定会给你一个“你以为不是但他说是”的东西。实际操作中我会把规范拆成几块功能目标、输入输出契约、硬性规则、软性建议、测试标准、禁止事项。硬性规则是模型不可违背的软性建议是模型可以弹性处理的。这里有个容易踩的坑有人把规范写成了长篇作文AI读起来也很“迷茫”。规范一定要短、要精确、要能量化。比如“密码需要哈希存储”不如“禁止明文存储密码强制使用bcrypt”让人放心。1.3 Harness驾驭层AI执行过程的“安全带与行车记录仪”有了规范和文档AI也不一定听话它会在生成过程中偏离方向甚至忘记前面设定好的约束。这时候就需要一个驾驭层也就是标题里的Harness。我习惯把它类比成汽车的辅助驾驶系统它不替你决定业务逻辑但会确保你不偏离车道遇到障碍能刹车全程还有行车记录仪。DeepSeek Harness是我用下来比较顺手的实现它的设计思路是把一次AI开发任务定义成一条工作流工作流里穿插模型调用、工具执行、规范加载、自动验证和人工审查。它和普通聊天式AI编程最大的区别是后者只有一个对话窗口你只能靠提示词约束AI而Harness把“规则、工具、流程、审计”全部外置了。就算AI中途发疯Harness也能用快照把它拉回上一格绿灯状态。Harness的关键能力有五个加载规范文件、编排多步工作流、调用插件执行本地工具、记录每一步审计日志、在工作流失败时回退到稳定快照。这五个能力合在一起才让AI辅助开发从“随机生成内容”变成了“可管理的工程项目”。2. 可控化体系整体设计从需求到交付的五个环节2.1 先写规范还是先跑流程顺序决定质量我在团队推广这套体系时遇到最多的抵触是“写规范太慢了”。但实际跑下来写规范的时间会在review和返工环节加倍省回来。我的流程是先把需求拆解成可验证的规范再让Harness去执行。规范写得越快越清晰后续返工越少。举一个实例。团队要加一个“用户注册接口”我填写的规范不会只有一句话而是包含接口签名、字段校验规则、错误码结构、性能要求、禁止事项。有人会觉得这些信息本来就要在需求文档里写为什么现在要提前因为过去需求文档是给人看的AI不会主动去读。现在通过Harness我可以把这份规范直接喂给模型并让它“只按这份spec实现”。一个可用的规范模板我现在是这样写的YAML形式后面第三章也会给完整示例目标字段写一句话契约字段写输入输出的类型硬性规则写死禁止事项写死测试标准写清楚覆盖率、性能指标。所有字段都是机器可读AI不会误解Harness也能在门禁节点自动校验。2.2 把工具链装进Harness不只是调API很多人以为可控化就是“给AI限制一下回答”实际上不够。AI要真正参与开发必须能调用本地工具执行单元测试、跑静态检查、查询项目结构、读文件、写文件。Harness在这里起到的是“工具总线”作用所有工具都通过插件方式接入。我目前的插件列表里最常用的有四个pytest执行器、ESLint静态检查器、GitDiff分析器、文件白名单守卫。每个插件都在工作流中被声明AI只能在白名单范围内调用。比如“文件白名单守卫”是一个特别有用的限制AI在生成代码时只能写指定目录下的文件不能去偷偷改数据库迁移文件或CI配置。这里有个经验插件不是越多越好。每加一个插件就多一层启动加载的复杂度和报错概率。我给团队的规矩是插件必须经过测试并且有明确场景不解决具体问题的插件一律不装。后面第四章会详细讲插件加载失败的排查案例。2.3 人工审查与自动验证的卡点设计有了规范和工具之后还要在流程里设置“门禁Gate”。门禁的意思是AI生成的代码不能自动进入主干必须通过一系列关卡。我设计了三个关卡格式门禁、逻辑门禁、人工门禁。格式门禁最简单先跑lint和format这一步能挡住大部分低质量输出逻辑门禁是单元测试和跨模块编译能挡住“自己把自己测绿”的假象人工门禁是最后一道由开发者查看diff重点看AI有没有“自作主张”。我要强调的是门禁顺序有讲究。一定是先机器后人工机器能过的再让人看否则人会被琐碎的格式问题淹没很快就麻痹了。自动回退也在这时生效。如果逻辑门禁失败达到一定次数工作流会直接回退到最近一个稳定快照并记录失败日志。这样才能保证AI无论怎么折腾主分支永远是绿的。2.4 反馈闭环让规范库越用越厚体系跑起来之后最重要的一步是把失败案例变成规范更新。每次人工review打回AI提交我都会顺手在代码评审意见里留下一句为什么打回。然后每周抽半个小时把这些打回理由归拢转写进spec的forbidden字段。比如第一周发现AI经常把业务异常吞掉只打印日志不抛出那就在spec里加一条“禁止在业务层捕获异常后静默返回必须转换为统一错误结构”。下一轮AI再生成就会避开这个坑。这样操作几周之后规范库会从最开始的10条规则涨到70条规则而AI生成代码的“返工率”也会逐渐下降。我把这个机制称为“教训的版本化”。它让人工审查的经验沉淀为组织资产而不是停留在某一个人的记忆里。2.5 插件与技能包的选型经验DeepSeek Harness里还有一个概念是“技能包Skill”。技能包比插件粒度更大通常是一整套针对某种任务的约束和工具组合。比如“数据库迁移技能包”会规定AI只能读取migration目录、必须生成可逆的up/down脚本、执行完后自动校验diff。这种包我觉得很好用但也很容易失控。选型技能包时我只看三个条件第一是不是高频重复任务第二是不是结果可自动验证第三是不是需要跨多个文件协作。如果这三个条件都满足就值得做技能包。如果只是偶尔用一次最好还是让人直接写不要让AI绕一圈。还要强调一点技能包需要有人维护。如果业务变了技能包里的规则没更新AI按旧规则干活反而比不用技能包更危险。3. 实战落地用“SDD规范Harness”搭建最小可行闭环3.1 落地前准备目录、版本与最小可用配置我在项目里一开始就把Harness相关文件独立成一个目录不跟业务代码混在一起。这样做的原因是规范库、工作流配置和业务代码的变更频率完全不同分开便于走各自的review流程。我的推荐目录结构如下my-project/ specs/ user-register.spec.yaml harness/ workflow.yaml plugins/ skills/ scripts/ verify.sh src/specs放所有开发规范harness放工作流和插件配置scripts放自动验证脚本。这套目录用git管理specs和harness都有独立的变更历史。AI生成代码时Harness会默认从当前工作区读取这些文件所以必须用相对路径不要写绝对路径否则换一台机器就崩。至于安装本身我不打算在这里贴命令因为工具版本迭代太快网上搜“DeepSeek Harness安装”会看到一堆新旧不一的教程。我建议直接看官方Release页找一个你系统的安装包或容器镜像先跑通一个示例工作流再开始改配置。3.2 定义一份机器可读的SDD规范从描述到契约我们拿“用户注册接口”这个非常常见的任务来演示。先写一个较完整的规范文件specs/user-register.spec.yamlapiVersion: spec/v1 kind: DevelopmentSpec metadata: name: user-register owner: backend-team spec: target: 实现用户注册接口输入邮箱和密码返回JWT和过期时间 contracts: input: email: string password: string captcha: string output: token: string expires_in: int hardRules: - 邮箱必须符合RFC 5322规范 - 密码长度至少12位必须使用bcrypt哈希存储 - 注册失败时返回统一错误结构 { code, message } - 同一邮箱在1分钟内不可重复注册 softRules: - 优先复用现有UserService - 不要新建无关的目录或类 testCriteria: - 单元测试覆盖率不低于80% - 接口性能P95响应时间低于500ms - 必须包含重复邮箱注册的测试用例 forbidden: - 禁止在业务层打印密码 - 禁止自行捕获全局异常 - 禁止引入Redis或消息队列等新依赖每个字段都是故意设计的。contracts字段让AI知道接口边界hardRules是不可谈判项softRules是建议项testCriteria是门禁脚本会自动检查的验收标准forbidden是“越界即回退”的红线。特别是forbidden我把团队过去踩过的几个坑直接写死在这里AI看到之后基本不会踩。3.3 写一份Harness工作流把规范变成执行计划有了spec之后我来配置工作流harness/workflow.yaml。这个文件的逻辑很简单加载规范让AI生成代码跑自动验证人工审查通过后提交。workflow: name: spec-driven-codegen steps: - id: load_spec use: spec_parser with: files: - specs/user-register.spec.yaml - id: generate use: llm_agent with: model: deepseek-coder temperature: 0.2 max_tokens: 3000 system_prompt: | 严格遵循spec中的hardRules和forbidden。 不允许新增需求不允许修改契约。 tools: - terminal - file_reader file_whitelist: include: - src/user/** exclude: - src/user/migrations/** - id: verify use: script_runner with: command: bash scripts/verify.sh retries: 2 on_failure: action: revert_to_snapshot snapshot: last_green - id: human_review use: git_diff_review with: require_approval: true - id: commit use: git_commit with: message: feat(user-register): implement registration endpoint这里有几个值得注意的设计选择。temperature: 0.2是我反复试出来的温度值太低会让输出机械重复太高会让代码“放飞自我”0.2在一致性和多样性之间最稳。file_whitelist用于限制AI只能改src/user/下的文件防止它顺手拨动其他模块。retries不是无限重试最多两个候选否则成本不可控。on_failure的回退目标我特意设为last_green即最近一次全部门禁通过的快照而不是工作流启动时的快照。3.4 关键参数与推荐经验值不是越大越好我在多次运行Harness之后整理了一张参数参考表供团队新入职同学直接抄作业。里面不一定完全适合你的项目但可以当一个起点。参数推荐值理由temperature0.20.3收敛到规范允许的范围减少随机创造性max_tokens20004000覆盖单模块生成太长容易跑偏重试次数12次超过2次收益急剧下降snapshot间隔每次门禁前失败后能回退到最近稳定点上下文窗口最多包含spec相关文件贪多会导致关键约束被遗忘超时时间单步5分钟让卡住的工作流尽快暴露参数背后都是经验。比如上下文窗口这个问题模型能力再强窗口也有限。如果你把整个仓库塞给AI它到后面可能已经忘了spec里的forbidden。所以我倾向于在generate步骤前由Harness根据spec自动算出需要哪些文件只把相关文件拼进prompt。这一步看起来不起眼但对输出质量影响极大。3.5 跑通一次完整流程从spec到review的现场记录下面我用一次实操记录来展示整个闭环是怎么运转的。我执行了一条命令名字不一定通用大概是harness run它会读取workflow.yaml并启动。第一阶段Harness加载spec然后把spec和src/user/下的现有文件打包给模型。模型开始生成代码输出两个候选diff。第二阶段脚本门禁自动运行verify.sh里包含了pytest、eslint和接口响应时间检查。第一个候选没过eslint被标记失败Harness自动记录失败原因并触发重试第二个候选通过所有自动检查。第三阶段进入人工review我看diff时发现一个细节AI在响应体里额外加了一个deprecated字段这个字段不在contracts里属于“AI自作主张”。我点击拒绝Harness没有直接提交而是回到通过自动门禁的第二个候选让我修改后重新确认。第四阶段我允许提交后Harness自动生成规范的commit message把代码推送到功能分支。整个过程记录在审计日志里包括每次生成了什么、哪个门禁失败、人工打回了哪一处。这种“全程留痕”的能力在需要追溯AI行为的时候特别有价值。4. 踩坑实录Harness使用中的常见问题与排查思路4.1 插件加载失败web boot未激活怎么查我遇到过最离谱的报错是启动Harness时出现类似“failed to load plugins web boot: 1 entry did not activate”的信息。第一次看到时完全懵后来才发现是插件目录里有一个插件的manifest配置不对。排查思路分三步。第一步看启动日志中具体哪个插件没有激活通常日志里会有插件路径。第二步打开该插件的manifest文件检查entry字段指向的实际文件是否存在以及文件是否导出了正确的激活函数。第三步用Harness自带的插件诊断命令检查依赖是否齐全有些插件依赖系统命令比如git如果环境变量没配好也会表现为启动失败。我的经验是插件加载失败90%都是“路径写错”或“依赖缺失”不要一上来就重装工具。另外不要在同一个Harness实例里堆十几个插件插件之间互相依赖很痛苦。我现在通常只保留5个以内其余按需开临时配置。4.2 Windows权限问题skill读取文件报setnamedsecurityinfow failedWindows上跑Harness的skill时经常遇到一个报错大概长这样setnamedsecurityinfow failed (win32)。这不是Harness本身的bug而是底层文件操作拿不到目标文件的修改权限。最常见的原因是进程运行在非当前用户权限下或者skill目录被放到了系统保护目录比如Program Files。我建议把Harness工作目录放到项目本地用普通用户权限运行项目目录的属主和运行用户必须一致。另外不要在开启“由管理员批准的写保护”的目录里建skillWindows下路径越深权限越麻烦。这个问题在Linux上也有变体表现为Read-only file system或Permission denied。排查方法类似看进程用户、目录属主、挂载权限。Skill本质上是帮AI读文件和写文件的工具文件系统权限不对后面所有流程都会挂。4.3 离线局域网部署模型、插件与规范库的配合很多团队问DeepSeek Harness能不能在完全断开外网的局域网里用。我负责任地说可以但需要提前把三样东西准备好。第一模型权重必须提前拉到内网并用统一模型网关封装成兼容接口这样Harness里只需要配置base_url指向内网网关。第二插件依赖要提前离线打包尤其是那些会在运行时下载外部组件的插件否则启动时会一直卡住。第三规范库和技能包要在内网git里有一份并且让Harness默认从内网仓库拉取。离线环境里真正的瓶颈不是模型能力而是验证脚本的完整度。因为AI生成的代码看起来正确没有联网环境很难快速验证真实行为。所以我建议在离线场景下把verify.sh写得比平时更严格多跑几层静态检查和单元测试把不确定性问题尽量拦截在门禁阶段。4.4 工作流卡死与上下文超限的快速定位工作流卡住通常发生在两个环节generate阶段或script_runner阶段。判断方法很简单查看Harness当前运行日志。如果卡在generate通常是模型服务超时或等了太久没返回如果卡在script_runner通常是验证脚本挂起比如测试里有等待外部服务的用例。上下文超限是我遇到第二多的原因。模型服务报“context length exceeded”时我会检查是不是把太多文件塞进去了。对策是给文件白名单加上范围限制再用Harness的摘要机制只给模型提供相关模块的函数签名和关键注释而不是整文件原文。这里我要说一个技巧把“可能变大的文件”目录排除在AI读取范围之外。比如自动生成的lock文件、构建产物、大的测试数据都应该在file_reader的ignore列表里。否则AI读着读着就忘了开始的规定。4.5 回退失灵快照应该从哪里来回退机制是整套体系的最后一道防线但它有可能失灵。我见过的情况是门禁失败后执行回退结果代码回到了旧版本但工作流状态没变下次生成还是在错误上下文上继续。原因在于快照的保存时机不对。正确的设计是每个门禁开始之前创建一个快照而不是失败之后才创建。我把快照分成代码快照和状态快照两部分。代码快照保存源码、依赖锁文件和spec文件状态快照保存Harness当前工作流的执行记录、已加载的上下文、以及哪些文件已被改动。这样回退才是一致性的回退否则代码回去了AI的“记忆”还在错误版本上等于白退。给团队的建议是回退功能上线前一定要做一次演练故意让代码门禁失败确认系统能恢复到指定状态。没有演练过的回退机制不能算可用。5. 从个人工作流到团队级AI辅助开发平台5.1 规范库的版本管理与共享当团队超过5个人之后spec就不能散落在个人项目里了。我把specs目录提到一个公共仓库用git子模块方式挂到各业务项目下。每个spec文件都带版本号修改时必须走MR和review流程合并后统一发布。我在spec元数据里加了owner字段每个规范有明确负责人。这样当业务规则变化时至少有人能第一时间知道该更新哪一份spec。规范本身也要做lint检查防止有人写了语义不对的YAML。这步可以放在CI里很简单。还有一个容易忽略的细节spec的变更要跟代码变更联动。如果某个接口的契约改了但spec没改下次AI按旧spec生成代码又会被人工打回。所以我会在CI里加一个检查要求“涉及contracts变更的MR必须同时修改对应spec文件”否则禁止合并。5.2 把Harness接进CI/CD个人工作流跑通之后下一步就是把Harness接进CI/CD让它成为团队基础设施的一部分。我目前的做法是在夜间任务里跑Harness生成的“AI代码质量报告”把一天内AI辅助产出的所有diff批量跑门禁生成通过率、打回率、回退率。CI里跑Harness和本地跑有一点不同CI环境是干净且隔离的本地的一些临时文件不会污染结果。但CI跑起来更贵每次都要启动插件、模型、验证脚本。所以不要对每个小commit都跑Harness而是对合并到release分支的MR跑一次“总审计”。另外一个经验是不要在正式构建的关键路径上放Harness它应该是一个旁路治理节点而不是阻塞节点。否则模型服务抖动一次整个发布流程都会卡住。5.3 多模型灰度切换用数据说话Harness把模型调用封装成了统一接口这让多模型灰度切换变得异常容易。我可以在同一份workflow.yaml里把model字段改成另一个模型名其他配置完全不变。为了安全我先让新模型处理低风险任务比如生成注释、补测试用例观察几天数据后再逐步扩大到核心代码生成。我用来做灰度决策的指标有三个门禁通过率、人工review打回率、回退率。新模型的门禁通过率如果没有明显更高就不值得切。因为AI辅助开发的核心目标不是“写得多”而是“减少返工”。只有数据支持切换我才会切换。这里有一个反直觉的发现有些看起来更“聪明”的大模型在严苛规则下并不比小模型更稳。因为大模型更喜欢自由发挥更容易违反forbidden。可控化体系会把模型之间的差异拉平这也是为什么要先立规矩再选模型。5.4 成本收益评估算清AI辅助开发的账做了这么多工作团队自然会问这套体系到底省不省钱我的建议是别拍脑袋记录一个月的运行数据再算账。我采用的简单公式是总成本 token费用 工具链资源成本 人工review工时收益 交付周期缩短量乘人天费率 线上缺陷减少带来的返工成本降低。token费用很容易从模型网关看到人工review工时需要给团队打点统计。第一周的数字往往不好看因为规范库还在积累AI频繁踩线人工打回率高。到第三四周随着forbidden规则越来越全通过率会明显提升。我见过最多的情况是一个月后总成本降低到第二周的40%左右。这套体系真正值钱的不是某个时刻的模型输出而是不断累积的规则资产和审计资产。我个人在实际操作中的体会是不要一开始就追求惊艳效果先把一条最频繁、最标准化的需求路径用SDD规范包起来再用Harness跑通。等这条路稳定了再复制到其他任务上。最后再分享一个小技巧把人工review时候顺手写的批注每周定期回填进spec的forbidden字段。这个动作看起来简单但它才是整个体系“越用越聪明”的真正原因。