用Harness思想打造AI Coding工程化：8个Skill串起研发全链路

最近圈子里聊AI Coding的人越来越多但大多数团队还停留在“把代码丢给AI让它生成一段是一段”的阶段。真正到了企业级落地你会发现单点生成代码根本撑不起一条完整的研发流水线需求理解得对不对、技术方案怎么定、代码风格统不统一、测试覆盖到没到、部署环节谁来盯、线上出问题谁来收尾——这些都不是一个Agent能自己搞定的。我最近在团队里做了一套基于Harness思想的AI Coding工程化方案用8个Skill把从需求到上线的全链路串了起来效果比之前零散调用模型好太多了。这篇文章把我整个设计思路、踩过的坑和落地细节都写出来给正在折腾AI Coding工程化的朋友一个参考。这里说的Harness本质上就是给Agent套的一层“运行轨道加操作手册”把大模型的能力约束在一个可控、可观测、可重试的工程环境里。而Skill则是轨道上的具体动作节点每个Skill对应一个明确的职责输入输出都有约定才能像流水线一样串起来。接下来我会把概念、8个Skill的职责拆解、实操配置和排查技巧完整地讲一遍。1. 先理清概念Harness、Skill、Agent 到底是什么关系1.1 用一条流水线来理解 Harness很多朋友一上来就问“Harness 跟 Agent 框架有什么区别”我的回答是Agent 框架解决的是“模型怎么循环推理、怎么调用工具”的问题而 Harness 解决的是“这套推理流程怎么被工程化地约束、编排和运维”的问题。一句话框架是发动机Harness 是整台车的底盘、线路和仪表盘。打个比方。你让一个实习生去独立完成一个小功能他不会一上来就写代码得先有个工位、有开发规范文档、有代码仓库的访问权限、有CI/CD管道出了问题还有监控和回滚机制。Harness 就是给 AI Agent 提供的这套“工位加规范加通路”。你不给Agent套Harness它就像个自带电脑但没工位、没权限、没流程的实习生水平和状态完全不可控。如果你们团队已经试过让AI自动改代码、自动修bug大概率遇到过这些问题AI改着改着把无关文件也动了AI明明说要跑测试结果没跑AI生成了代码但没人知道它依据什么规范写的AI连续调用同一个工具5次全失败还在重试。这些问题都不是模型能力不够而是少了Harness这层“工程约束”。1.2 Skill 不是插件是“操作手册”关于Skill很多人有误会。Skill不是那种装进去就能用的现成插件它本质上是一段把“怎么做某类事情”写得极其清晰的标准作业程序。我给Skill下的定义是一份带输入输出契约、执行步骤、质量校验规则和能力说明的结构化指令包。为什么需要把Skill单独抽出来因为如果你把完整的研发流程塞进一条System Prompt里模型会严重“迷失方向”上下文一长它就忘了前面而且维护起来也是噩梦。把流程拆成多个Skill等于把一个3000字的复杂指令拆成8份300字的精准指令每个Skill的职责边界清楚模型在每个阶段只需要专注做一件事。再打个比方。你不会让一个新员工一上来就同时负责需求分析、写代码、测试、部署、写文档。你肯定希望他先专心做需求分析做到位了把成果传递给下一个人。Skill就是这样的“岗位职责说明书”。2. 全链路拆解为什么恰好是这 8 个 Skill2.1 从需求到上线的完整环节我先把我理解的企业级AI Coding全链路拉出来。一条标准的研发流水线大致是需求理解与分析、方案设计、代码实现、代码审查、测试执行、文档沉淀、发布部署、线上反馈收集。这8个环节不是拍脑袋定的它是研发流程的骨架少了任何一个环节整条链路都会出现“无人值守的真空地带”。再加上一个背景企业级跟个人玩最大的区别在于“可交付”和“可审计”。个人用AI生成一段代码自己能跑就完了企业里每一行AI写的代码都要能追溯到需求来源、设计决策、测试结果和发布记录。这才是我强调“全链路”的根本原因——不是把活干完而是把活干得人人都能接手、出了问题找得到根因。2.2 Skill 的边界划分原则在给流程划Skill时我坚持一个原则一个Skill只解决一类问题相邻Skill之间的交接物必须是结构化的数据而不是“再帮我看看”这种模糊指令。这8个Skill的划分是一个横向的流水线但在实现上每个Skill内部还可以有纵向的子步骤。比如“代码审查Skill”内部就分静态检查、逻辑审查、安全扫描三层。你不把子步骤定义清楚模型审查的时候就只会“走过场”说不出真正的问题。2.3 Skill 之间的输入输出契约这是整套工程里最容易被忽视、但影响最大的一点。8个Skill如果想串成链路就必须约定好每个Skill吐出来的数据格式。我这里统一采用结构化JSON举个例子需求理解Skill输出一个包含“功能描述”“验收标准”“依赖项”“风险点”的JSON对象方案设计Skill读取这个JSON产出包含“技术选型”“接口设计”“数据模型”“变更影响面”的JSON代码实现Skill再基于方案JSON去写代码。有了这套契约任何一个Skill的输出都可以被下一个Skill稳定消费也可以被外层Harness记录和审计。模型输出不太稳定的时候外层的校验器会做一次JSON Schema校验不合格就打回重试。这一步非常关键后面实操部分我会给具体配置。3. 8 个 Skill 逐个拆解职责、要点和坑3.1 Skill1需求理解与拆分Requirement Skill这个Skill的输入是一段比较原始的需求描述输出是结构化的需求规格。它要解决的核心问题是把业务方那句“我想要一个登录功能”翻译成研发能动手干活的精确描述。实操时有三个要点必须让模型区分“事实描述”和“隐含假设”。比如需求里说“用户登录后跳转到首页”隐含假设是“登录态要持久化、会话过期要处理”。模型如果能自动列出隐含假设后面会少很多返工。验收标准必须是可执行的描述比如“输入正确用户名密码后3秒内返回登录成功”而不是“登录要快”。我加了一条硬校验如果模型没有拆出“风险点”字段就自动触发一次追问而不是放行。踩过的坑一开始需求理解Skill输出太“虚”全是“系统需要提升用户体验”这种正确的废话。后来我加了一个约束每个验收标准必须能映射到至少一个测试用例否则视为无效输出。这招很管用。3.2 Skill2架构方案生成Architect Skill架构方案Skill读需求规格产出技术方案。这里比较容易翻车因为模型生成的方案经常“大而全”不分等级看起来什么都说了其实什么指导价值都没有。实操要点分层产出。第一层给出总体技术选型比如用微服务还是单体、选什么数据库第二层给出模块划分和接口定义第三层才进入到表结构和关键类设计。一次性让模型输出全量架构它一定会漏东西。强制声明“变更影响面”。动了哪个模块、会影响哪些下游服务、是否需要同步改数据库这些必须在方案里写清楚否则后面代码实现会失控。数据模型设计必须给出字段级定义类型、约束、索引缺一不可。数据模型含糊代码实现Skill就会自由发挥。这个Skill依赖需求JSON里的功能描述和风险点方案输出的质量直接决定后续代码实现的上限。我建议架构Skill允许调用外部工具去搜索依赖库的版本信息和兼容性减少模型闭门造车的概率。3.3 Skill3代码实现Coding Skill这是最核心的Skill也是大家最熟悉的。代码实现Skill不是简单地说“写代码”它要解决三个问题代码风格统一、上下文完整、改动范围可控。实操要点必须要绑定仓库的代码规范文档。我在Skill里会引用一份项目自己的《编码规范.md》让模型严格按照其中的命名、注释、目录结构、异常处理规则来写。改动范围控制。模型容易顺手把不相干的文件也改了。我在Skill里有一条硬命令只能操作方案里允许的文件清单超出范围的变更一律标记为异常。这招能挡住至少一半的手贱乱改。代码自检。写完代码后模型必须生成一份“变更说明”列出改了哪些文件、每个文件改了什么、为什么改。这份变更说明不只是给人看的也是后续审查Skill的输入。踩过的坑让Coding Skill直接读整个仓库上下文Token消耗直接爆炸而且模型注意力全被无关代码分散。后来我改成只加载变更影响面相关的文件和接口定义效果就好了很多。3.4 Skill4代码审查Review Skill审查Skill是质量闸门它的价值不只是“挑毛病”更是把抽象的质量标准变成具体可执行的检查项。没有这道闸门AI写的代码就直接流向测试和发布风险不可控。实操要点审查要分类型逻辑正确性、代码规范、性能隐患、安全漏洞、可维护性每个类型单独过一遍避免混在一起模糊处理。每个问题必须给建议修复方向不能只说“这里有问题”。我发现让模型提修复建议本身就是一次思维校准它提不出来修复建议的问题大概率是误报。严重级别分级阻塞性问题必须修、建议性问题尽量修、可忽略问题记录即可。没有分级开发人员看到满屏问题就麻了最后全都不改。时间长了你会发现Review Skill更像是一个“质量翻译器”它把代码质量这个抽象概念翻译成一个个具体问题并交给后续环节处理。3.5 Skill5测试生成与执行Test Skill测试Skill是很多团队忽略的一环但在我看来它是企业级AI Coding的底线。没有测试闸门AI写的代码就是裸奔一旦上线出问题损失的可不只是时间。实操要点先生成测试计划再生成测试代码。测试计划包括要测哪些函数、覆盖哪些分支、边界值是什么、Mock哪些外部依赖。计划确认了再写代码避免瞎写。执行测试时Harness要为Skill提供一个沙箱环境。不是让模型自己跑测试而是Harness统一调度测试命令把失败信息回传给模型做修复。覆盖率报告必须输出哪怕只是行覆盖率。这个报告会作为后续发布决策的一个依据。踩过的坑测试Skill如果让模型自己决定“测到哪算哪”它一般只会写Happy Path的用例。我在Skill里加了一条每个被测函数必须包含至少一个异常路径的用例。效果立竿见影很多隐藏的问题在前期就暴露了。3.6 Skill6文档生成Document Skill文档Skill把前面所有环节的信息聚合成文档。我要求它输出两类文档面向开发者的技术说明和面向后续维护者的变更记录。实操要点技术说明要包含设计背景、接口文档、数据模型和部署注意项不是简单的“代码注释汇总”。变更记录要跟需求规格里的需求ID挂钩这样就能实现从需求到发布的完整追溯。这条看着简单实际上对团队协作特别重要。文档的长度要有上限。我见过AI生成上万字的“技术文档”根本没人看。我限制它控制在500行以内保留核心信息即可。文档这个环节最容易被砍掉但真实环境里团队人员流动、架构老化和知识断层往往就是因为文档缺失。AI把文档自动补齐之后交接成本会低很多。3.7 Skill7发布部署Release Skill发布Skill是执行者它负责把已通过测试的代码部署到目标环境。在Harness体系里发布Skill跟前面的Skill有个本质区别它要操作外部系统所以必须有权限控制和审批节点。实操要点用“预检清单”机制。发布前逐项确认测试是否通过、变更是否已记录、目标环境是否正确、是否有未关闭的阻塞性问题。灰度发布是强制的。不允许一次性全量发布必须先发布到金丝雀节点观察后再滚动。任何发布动作都要记录审计日志包括发布时间、操作者、版本号和结果。这个对企业来说不是可选项是必选项。发布Skill做得好不好直接决定运维团队对你这套AI Coding体系的信任度。它必须表现得比人更谨慎才会有人愿意把发布权限交给系统。3.8 Skill8反馈收集与迭代Feedback Skill最后一个Skill容易被人忽略但它是闭环的关键。代码上线后不是结束而是新的开始。没有反馈闭环你永远不知道AI写出来的东西在生产环境表现如何。实操要点定义“反馈来源”日志异常、用户工单、监控告警、指标波动。模型需要定期扫描这些来源发现异常就归类并生成问题报告。问题报告要关联到需求ID和代码变更记录这样必要时可以直接触发新一轮的修复链路。我会在Feedback Skill里加一条“止损优先”原则遇到重大线上问题第一步不是让AI分析根因而是先回滚或降级保住可用性然后再走分析流程。这是上线后最该有的敬畏心。4. Harness 工程化实操8 个 Skill 怎么真正串起来4.1 Skill 注册统一描述结构我采用一种类似清单文件的方式来注册每个Skill里面有名字、描述、输入Schema、输出Schema、最大重试次数、是否允许外部工具调用等字段。描述字段特别重要它不是给人看的注释而是给“编排器”看的编排器会根据描述来决定当前上下文应该触发哪个Skill。贴一段我当时注册Skill时的伪配置具体结构你按自己团队的框架来改skills: - name: requirement description: 用于将原始需求转化为结构化需求规格输出验收标准和风险点 input_schema: raw_requirement.md output_schema: requirement.json max_retries: 3 allow_tools: false - name: architect description: 基于需求规格生成技术方案包含数据模型和变更影响面 input_schema: requirement.json output_schema: architecture.json max_retries: 2 allow_tools: true - name: coding description: 基于技术方案实现代码变更只允许修改指定文件清单 input_schema: architecture.json output_schema: change_set.json max_retries: 5 allow_tools: true - name: review description: 对变更集做代码审查输出分级问题列表和修复建议 input_schema: change_set.json output_schema: review_report.json max_retries: 2 allow_tools: true4.2 编排逻辑谁来决定下一个 Skill 是谁很多人以为编排逻辑是“写完代码就自然去审查”其实没那么简单。我的做法是Harness维护一张有向图每个Skill是节点节点之间有条件和顺序约束。当前Skill执行完后校验输出Schema然后根据输出数据和图上定义的跳转规则决定下一步。比如代码实现Skill完成后如果变更集为空直接终止链路并告警不再往下走如果非空进入审查Skill。审查Skill完成后根据问题严重级别分流有阻塞性问题则回到Coding Skill修复只有建议性问题则直接放行进测试。这套规则写死在Harness配置里不靠模型自己决定——模型适合做理解推理不适合做流程编排因为它会编着编着就跳步。提示如果你准备直接抄作业建议先把第4.4节“输出校验器”看明白这是整个Harness工程的命门。4.3 上下文窗口怎么管理企业级项目动辄几十万行代码不可能把整个仓库塞进上下文。我的经验是三层上下文策略全局层只放项目说明文档、目录结构、编码规范大约1到2万Token所有Skill共用。任务层当前Skill需要的输入数据比如需求JSON、方案JSON、变更文件清单约1万Token。文件层具体代码文件内容按需加载控制在3万Token以内。三层加起来控制在5万Token以内响应速度和准确率都能兼顾。等未来模型上下文窗口变大之后这个策略可能要调整但就当前阶段来说这是最稳的做法。我在Harness里做了一个简单的“上下文加载器”每次加载文件时先读文件索引再根据当前Skill的意图只把相关文件片段放进上下文。实际跑下来比“全仓塞”准确率高很多而且省下的Token成本也很可观。4.4 输出校验器最后一道防线模型输出不可靠是现实所以我给每个Skill都配了一层输出校验器它负责三件事格式校验、内容质检、契约检查。格式校验是检查JSON结构是否合法、字段是否齐全。内容质检会根据当前Skill定制的规则做检查比如需求Skill要检查是否包含风险点字段代码Skill要检查是否改动了非白名单文件。契约检查则是确认这个Skill的输出是否满足下一个Skill的输入要求。校验不通过的输出会带着失败原因重新触发Skill重试。重试超过上限就进入人工介入队列由开发人员处理。这套“机器先行、人工兜底”的机制让整个链路的安全边界非常清晰也解决了很多人担心的“AI乱来没人管”的问题。5. 常见问题与排查技巧实录5.1 高频翻车现场我整理了实际使用中遇到的高频问题做成了速查表你们可以直接对照排查现象根因解决办法AI频繁改无关文件Coding Skill没有白名单约束给Skill增加文件清单白名单非白名单变更一律拒绝需求理解输出全是空话缺少“验收标准可映射测试”的硬校验需求Skill增加规则验收标准必须能对应到测试用例审查Skill报的问题全是误报审查维度混在一起模型思维发散强制审查类型拆分每个类型单独过一遍测试只写了正常路径用例Test Skill缺少异常路径约束增加规则每个函数至少有一个异常路径测试链路中断后无法定位缺少结构化审计日志记录每次Skill调用的输入输出、耗时、重试次数模型上下文溢出一次性加载太多文件使用三层上下文策略按需加载反馈Skill误报线上故障告警阈值或过滤条件太粗给反馈Skill定义明确的过滤规则关联监控指标5.2 Skill 编排串错的定位技巧如果你发现链路在某个节点莫名其妙停了先不要怀疑模型八成是输出校验器拦截了。去查审计日志看校验器返回的失败原因是什么再针对性调整Skill提示词或校验规则。有个小技巧给每个Skill的输出加上版本号比如requirement.json里有个schema_version字段。这样一旦下游解析报错你能立刻判断是数据结构变更导致的不兼容还是模型输出格式本身有问题。我因为这个字段少排查了很多无效问题。5.3 效果衡量不要只看“代码生成对不对”很多团队评估AI Coding效果只盯着“模型一次生成通过的代码比例”这是不对的。企业级落地更要看的是全链路指标需求流转效率、人工介入频率、线上故障数变化、审计追溯完整性。我习惯看三个核心数字端到端无人值守通过率即从需求进入链路到发布完成全程不需要人工介入的比例。平均单需求耗时对比人类研发团队的基线看AI Coding到底省了多少时间。线上问题回退率这个数字最能说明质量闸门到底有没有用。我实测下来我们的链路在优化一个月后无人值守通过率从18%涨到了43%单需求耗时平均降了约一半。当然这个数字跟需求复杂度强相关简单需求通过率高复杂需求该人工介入还是得人工介入不必为了追求指标硬撑。6. 落地一个月后我的几条实战心得这套8个Skill串全链路的方案我陆陆续续调整了大概一个多月才稳定。说实话一开始我也天真地以为把流程列出来就完事了真正跑起来才发现工程化的难点从来不在于流程列表本身而在于每个节点之间咬合的细节输出Schema稳定不稳定、校验规则细不细、上下文切换顺不顺、人工兜底的入口好不好用。任何一个环节粗糙整条链路的可靠性都会被拖垮。最后分享一个我个人的心得如果你刚开始做Harness工程化不要一上来就想搞8个Skill全链路先把最核心的“Coding加Review加Test”三角色跑通再往外延伸。全链路看起来性感但复杂度是几何级增长的。先把三角色的输入输出契约咬死把校验器做好再逐步加新Skill成功率会高很多。另外提醒一句Skill的提示词不是写一次就完的要持续根据实际失败案例迭代。我每个月都会把校验器拦截的失败样本拉出来分析是模型理解问题还是规则设计问题然后针对性调整。这套用数据驱动Skill迭代的方法才是Harness工程能越跑越顺的核心。