★ FEATURED ARTICLE 1. 从 Vibe Coding 到生产可用一个 Coding Agent 调优项目的完整复盘Vibe Coding 这个词从去年火到现在很多人已经用它写了不少小工具、脚本、甚至完整的 Demo 项目。但真正把 Coding Agent 丢进生产环境跑起来的人都知道Demo 能跑通和线上稳定交付之间隔着一条巨大的鸿沟。我最近花了将近三周时间在一个基于华为内部工程体系的生产级 Coding Agent 项目上做效果调优从最初的“能写代码但经常跑偏”到最终在真实业务仓库里达到可交付的准确率中间踩的坑、试过的方案、推翻重来的决策值得完整记录一遍。这个项目的核心目标很明确让 Coding Agent 在华为内部的代码仓库、构建流水线和代码审查规范下能够自主完成从需求理解到代码提交的完整链路。听起来像是又一个“AI 写代码”的故事但实际做下来真正花时间的不是模型选型而是 Harness 层的工程化调优——也就是怎么把模型的原始能力通过提示词、工具链、上下文管理、回退机制等手段稳定地“驾驭”到生产标准。如果你正在做 Coding Agent 的落地或者对 Vibe Coding 的生产化路径感兴趣这篇实录应该能帮你省下不少试错时间。我会从整体设计思路讲起然后拆到 Harness 工程的核心细节再到实操调优的具体步骤和参数最后把踩过的坑和排查方法整理成速查表。内容偏工程实战不涉及任何敏感信息所有案例都做了脱敏处理。2. 整体设计与思路拆解为什么 Harness 才是决胜点2.1 生产级 Coding Agent 和 Demo 的本质区别先说说我理解的“生产级”到底意味着什么。Demo 阶段你让 Agent 写一个排序算法、生成一个 CRUD 接口它表现很好因为这类任务边界清晰、上下文自包含、验证标准单一。但生产环境里的编码任务完全是另一回事需求描述可能来自一份不完整的会议纪要代码要嵌入一个有几万行历史代码的仓库构建流程有严格的静态检查和单元测试门槛代码审查还有团队自己的规范。我一开始也以为只要模型够强就行但实测下来同一个模型在 Demo 场景和生产场景的表现差距可以大到让你怀疑是不是换了模型。后来想明白了模型能力是上限Harness 工程决定你能多接近这个上限。Harness 这个词在 Agent 领域指的是“驾驭层”——所有模型之外、但直接影响模型输出的工程手段的总和。它包括提示词编排、工具定义、上下文注入、输出解析、错误回退、状态管理等等。一个直观的类比模型是发动机Harness 是变速箱和底盘。发动机再好变速箱匹配不好车也跑不快、跑不稳。2.2 为什么选择“重 Harness、轻模型”的路线项目初期我们讨论过两条路线一是等更强的模型二是把 Harness 做厚。最终选了后者原因有三个。第一生产环境的约束是刚性的。华为内部的代码规范、构建工具链、审查流程不会因为模型变强就自动适配这些必须由 Harness 层来桥接。第二模型迭代不可控但 Harness 的每一行代码都是我们自己能掌控的调优的确定性更高。第三从成本角度看把 Harness 做厚之后对模型版本的依赖降低后续切换模型时迁移成本小很多。具体来说我们的 Harness 层承担了这些职责把用户模糊的需求转成结构化的任务描述、从代码仓库中检索相关上下文、调用工具执行代码修改和验证、解析模型输出并做格式校验、在失败时触发回退和重试、维护多轮对话的状态一致性。这些环节每一个都有调优空间后面会逐个展开。2.3 核心架构的分层设计整个系统我把它分成四层从下到上依次是模型接入层、Harness 工程层、工具执行层、交互反馈层。模型接入层负责统一不同模型的调用接口屏蔽差异。Harness 工程层是核心包含提示词模板、上下文管理器、输出解析器、回退控制器。工具执行层封装了代码检索、文件读写、命令执行、测试运行等原子能力。交互反馈层处理用户输入和 Agent 输出的呈现。这个分层的好处是每层可以独立调优。比如提示词效果不好只需要改 Harness 工程层不用动工具执行层。实测下来这种分层让调优效率提升很明显因为你能快速定位问题出在哪一层。3. 核心细节解析与实操要点Harness 工程的五个关键模块3.1 提示词编排从“一句话需求”到“可执行任务”提示词是 Harness 层最直接影响模型输出的部分。我试过很多种写法最后稳定下来的结构是四段式角色定义、任务拆解、约束条件、输出格式。角色定义不是简单写“你是一个程序员”而是要具体到技术栈和工程规范。比如“你是一个熟悉 Java 和 Spring Boot 的后端工程师遵循阿里巴巴 Java 开发手册和团队内部的代码审查清单”。这样模型在生成代码时会自然带上规范意识。任务拆解部分我会把用户的一句话需求先做一次结构化。比如用户说“给用户模块加一个批量导出功能”我会在提示词里拆成需要修改哪些文件、需要新增哪些接口、需要哪些依赖、需要写哪些测试。这个拆解过程本身可以用一个小模型来做也可以用规则引擎我们最终用的是规则加小模型混合的方式。约束条件是最容易被忽略但最重要的部分。我会明确写出不允许修改公共工具类、新增依赖必须经过审批、所有公开方法必须有 Javadoc、单元测试覆盖率不低于 80%。这些约束直接决定了生成代码能不能通过后续的构建和审查。输出格式我强制要求模型返回结构化的 JSON包含文件路径、修改类型、代码内容、测试用例四个字段。这样后续的解析和校验会简单很多。实操心得提示词里的约束条件不要超过 7 条超过之后模型会开始“遗忘”前面的约束。如果确实有很多约束拆成多轮对话每轮聚焦 3 到 4 条。3.2 上下文管理怎么让模型“看到”该看的代码生产仓库动辄几万行代码不可能全塞进上下文窗口。上下文管理的核心是“精准检索”而不是“尽量多塞”。我们的做法是三层检索第一层基于文件路径和模块名做粗筛第二层基于代码符号类名、方法名做精确匹配第三层基于语义相似度做补充召回。三层结果合并后按相关性排序取 Top N 注入上下文。这里有个关键参数是上下文窗口的分配比例。我实测下来给“相关代码”留 60%给“任务描述和约束”留 25%给“历史对话”留 15% 是比较稳的。如果历史对话占比过高模型容易被之前的错误带偏。另一个细节是代码片段的截断策略。不要简单按行数截断而是按语法结构截断。比如一个方法太长优先保留方法签名和关键逻辑分支省略中间的日志和异常处理。这个策略让模型对代码结构的理解准确率提升了不少。3.3 工具定义原子能力的粒度控制工具定义看起来简单其实很讲究粒度。粒度太粗模型不知道怎么组合粒度太细模型会在无关工具上浪费轮次。我们最终定义了 12 个原子工具分成四类检索类搜索代码、查找符号、读取文件、修改类写入文件、替换代码块、新增文件、验证类运行单测、运行静态检查、编译、辅助类查看目录结构、查看依赖、查看 Git 状态。每个工具的描述里我会明确写出“什么时候用”和“什么时候不用”。比如“搜索代码”工具的描述里会写当你需要查找某个功能的现有实现时使用当你已经知道文件路径时直接用读取文件工具不要用搜索。注意事项工具的数量和模型的轮次预算要匹配。如果一次任务只给模型 10 轮那工具不要超过 8 个否则模型会在选择工具上消耗太多轮次。3.4 输出解析与校验把“自由文本”变成“可执行指令”模型输出是自然语言和代码的混合体直接执行风险很高。我们的解析器分三步格式校验、语义校验、安全校验。格式校验检查 JSON 结构是否完整、必填字段是否存在。语义校验检查文件路径是否在允许范围内、代码是否符合基本语法、测试用例是否覆盖了修改点。安全校验检查是否引入了不允许的依赖、是否修改了受保护的文件、是否包含敏感信息。任何一步校验失败都会触发回退控制器。回退控制器会根据失败类型决定是重试、换策略还是上报人工。实测下来格式校验的失败率最高主要原因是模型在长输出时容易漏掉 JSON 的闭合括号。后来我们在提示词里加了“输出前先检查 JSON 完整性”的指令失败率降了一半。3.5 回退机制让 Agent 学会“知难而退”回退机制是生产级 Agent 和 Demo 级 Agent 最明显的分界线。Demo 里模型错了就错了重新问一次就行。生产环境里错误的代码修改可能污染仓库、触发错误的构建、甚至影响其他同事的工作。我们的回退策略分三级一级回退是原地重试适用于格式错误和轻微语义错误二级回退是换策略重试适用于同一问题连续失败两次的情况比如换一种检索方式、换一个提示词模板三级回退是终止并上报适用于涉及受保护文件或连续失败三次以上的情况。这里有个经验回退不是越多越好。我一开始设置了无限重试结果模型在一个死循环里反复修改同一个文件浪费了大量 token。后来改成最多两级回退、总轮次不超过 15 轮效率反而更高。4. 实操过程与核心环节实现从零到可交付的调优记录4.1 环境准备与基础配置项目启动前先把基础环境搭好。我们用的是华为内部的开发环境代码仓库、构建工具、测试框架都是现成的。需要额外配置的主要是 Agent 的运行环境和 Harness 工程的依赖。运行环境方面我建议用容器化部署把模型调用、工具执行、文件系统隔离在不同的容器里。这样即使 Agent 执行了危险命令也不会影响宿主机。我们用的是 Docker Compose 做本地开发生产环境用 K8s 编排。Harness 工程的依赖不多核心是 HTTP 客户端、JSON 解析库、代码解析库我们用 JavaParser 做 Java 代码的语法分析、向量检索库用于语义召回。版本上建议锁定避免因为依赖升级导致行为变化。配置项里最重要的是模型调用的超时和重试参数。我设置的是单次调用超时 60 秒、最多重试 2 次、重试间隔 5 秒。这个参数是根据实际网络环境和模型响应时间调出来的太短容易误判超时太长会拖慢整体流程。4.2 提示词模板的迭代过程提示词模板我前后改了 11 版这里挑几个关键迭代说一下。第一版是“你是一个程序员请完成以下任务”效果很差模型生成的代码风格随意、缺少注释、经常忽略约束。第二版加了角色定义和约束条件效果明显提升但模型开始“过度设计”简单任务也生成一堆抽象类和接口。第三版加了“保持最小改动”的约束并明确写出“优先修改现有代码而不是新增文件”过度设计的问题基本解决。第五版开始引入结构化输出要求模型返回 JSON。这一版遇到了新问题模型在 JSON 里嵌套了 Markdown 代码块导致解析失败。后来在提示词里明确写“代码内容用纯文本字段不要嵌套 Markdown 标记”问题解决。第九版是针对多轮对话的优化。我们发现模型在第二轮之后容易忘记第一轮的约束于是在每轮提示词里都重新注入核心约束。这个改动让多轮任务的准确率提升了大约 20%。实操心得提示词模板一定要版本化管理每次改动都记录改了什么、为什么改、效果如何。我用一个简单的 CSV 记录后来复盘时帮了大忙。4.3 上下文检索的参数调优上下文检索的核心参数有三个召回数量、相关性阈值、窗口分配比例。召回数量我试过 5、10、20、50 四档。5 太少经常漏掉关键代码50 太多模型注意力被分散。最终定在 15配合相关性阈值 0.75效果最稳。相关性阈值是语义检索的分数门槛。设太高会漏召回设太低会引入噪声。0.75 是在我们的代码库上实测出来的不同代码库可能需要调整。调整方法是人工标注 50 个查询的相关代码然后看不同阈值下的召回率和准确率取 F1 最高的点。窗口分配比例前面提过60/25/15 是通用配置。但如果任务特别复杂比如涉及跨模块重构我会把相关代码的比例提到 70%历史对话压到 10%。4.4 工具调用的轮次控制工具调用的轮次控制是个动态平衡。轮次太少任务完不成轮次太多成本和延迟都上去了。我们的策略是按任务复杂度分档简单任务单文件修改给 8 轮中等任务多文件修改加测试给 12 轮复杂任务跨模块重构给 20 轮。这个分档是根据历史任务的成功率和平均轮次统计出来的。实际运行中如果模型在预算的 70% 轮次内还没完成系统会触发一次“进度检查”让模型总结当前进展和剩余工作。这个检查能帮模型重新聚焦避免在细节上过度纠缠。4.5 验证环节的自动化集成验证环节是保证代码质量的关键。我们把单元测试、静态检查、编译三个验证步骤自动化集成到 Agent 的工作流里。模型生成代码后Harness 层会自动触发验证。如果单元测试失败会把失败信息反馈给模型让它修复。如果静态检查报错同样反馈。如果编译失败反馈编译错误。这个反馈循环最多执行两轮两轮后仍失败就上报人工。实测下来单元测试的反馈最有效模型修复测试失败的成功率在 70% 左右。静态检查的反馈效果一般因为很多规范问题模型“知道但做不到”需要人工介入。编译错误的反馈效果最好基本一轮就能修复。5. 常见问题与排查技巧实录5.1 模型输出格式错误的排查格式错误是最常见的问题表现是 JSON 解析失败、字段缺失、类型不匹配。排查思路是先看原始输出确认是模型没按格式输出还是解析器太严格。如果是模型没按格式输出检查提示词里的格式说明是否足够明确。我遇到过提示词里写了“返回 JSON”但模型返回了 JSON 加解释文字的情况。后来改成“只返回 JSON不要有任何其他文字”问题解决。如果是解析器太严格比如模型返回的 JSON 里数字是字符串类型解析器直接报错。这种情况可以在解析器里加类型兼容处理把字符串数字转成数字。5.2 上下文检索不准的排查检索不准的表现是模型生成的代码和现有代码风格不一致、重复造轮子、引用了不存在的类。排查思路是先看检索结果确认是没召回到相关代码还是召回了但模型没用。没召回到的情况检查检索查询的构造。我们一开始直接用用户需求做查询效果不好。后来改成先用小模型把需求转成技术关键词再用关键词检索召回率提升明显。召回了但模型没用的情况检查上下文里的代码片段是否被截断得太厉害。我遇到过关键方法被截断模型只看到方法签名没看到实现于是自己重新实现了一遍。后来调整了截断策略优先保留方法体。5.3 工具调用死循环的排查死循环的表现是模型反复调用同一个工具、反复修改同一个文件、轮次用完了还没进展。排查思路是看工具调用的历史记录找到循环的起点。常见原因是工具返回的错误信息不够明确模型不知道该怎么修正。比如文件写入失败工具只返回“写入失败”模型不知道是路径问题还是权限问题于是反复重试。后来我们在工具返回里加了具体的错误原因和修复建议死循环明显减少。另一个原因是提示词里缺少“如果连续失败两次就换策略”的指令。加上这条之后模型会主动切换方法而不是一条路走到黑。5.4 常见问题速查表问题现象可能原因排查方法解决措施JSON 解析失败模型输出含额外文字查看原始输出提示词强调只返回 JSON代码风格不一致上下文未召回规范代码检查检索结果优化检索查询构造重复造轮子未召回到现有实现检查符号检索增加符号匹配权重工具调用死循环错误信息不明确查看调用历史丰富工具返回信息多轮后遗忘约束约束未重复注入检查每轮提示词每轮重新注入核心约束测试修复失败反馈信息不足查看测试输出提取关键失败信息反馈编译错误反复模型不理解编译规则查看编译日志提供编译规则说明轮次耗尽未完成任务复杂度评估不准统计历史轮次调整分档预算5.5 独家避坑技巧第一个技巧在提示词里加一句“如果你不确定先问我”。这看起来简单但能避免很多模型“自作主张”导致的错误。实测下来加了这句话之后模型主动询问的比例从 5% 提升到 25%而主动询问的任务成功率比自作主张的高出 40%。第二个技巧给模型一个“逃生通道”。在工具列表里加一个“上报问题”工具模型遇到无法解决的问题时可以调用它而不是硬着头皮乱改。这个工具的存在让模型的“焦虑感”降低输出质量反而更稳定。第三个技巧定期用历史任务做回归测试。我们每周会抽 20 个历史任务重新跑一遍看成功率有没有下降。这个习惯帮我们及时发现了几次因为依赖升级导致的性能退化。6. 调优后的效果与后续扩展方向经过三周的调优Agent 在真实业务仓库上的表现从最初的“能跑但不可用”提升到了“可交付”。具体指标上简单任务的成功率从 45% 提升到 88%中等任务从 30% 提升到 72%复杂任务从 15% 提升到 55%。代码审查的一次通过率从 40% 提升到 78%。这些数字不是终点但已经足够让团队愿意把它纳入日常开发流程。后续我打算在几个方向继续扩展。一是把 Harness 工程的经验沉淀成可复用的框架让其他团队不用从零开始。二是探索多 Agent 协作让一个 Agent 负责编码、一个负责审查、一个负责测试通过分工提升复杂任务的成功率。三是把调优过程中积累的提示词模板和工具定义整理成内部文档降低新人的上手成本。这个项目做下来我最大的体会是Coding Agent 的生产化模型能力只是起点Harness 工程才是真正的战场。那些看起来“不酷”的工程细节——提示词的措辞、上下文的截断策略、工具的错误信息、回退的触发条件——才是决定 Agent 能不能在生产环境活下来的关键。如果你也在做类似的事情建议把至少 70% 的精力放在 Harness 层剩下的 30% 再去看模型。
阅读完成 · 觉得有帮助？
