1. 从能跑通到敢上线生产级 Coding Agent 的真实鸿沟Vibe Coding 这个词这两年被聊得很多大意是用自然语言把意图丢给 Coding Agent让它自己读代码、改代码、跑测试人只负责感觉对不对。Demo 阶段确实爽一个 prompt 下去几十行代码就出来了。但真正把它放进生产环境、接进企业级研发流水线之后你会发现一个很尴尬的事实能跑通和敢上线之间隔着一条比想象中宽得多的沟。我自己参与过几轮 Coding Agent 的落地调优最大的感受是——模型能力只是入场券真正决定成败的是模型外面那一圈东西。圈内现在有个词叫Harness直译是马具、挽具非常形象模型是那匹有劲但方向不定的马Harness 就是套在它身上、把它的力气导向正确方向的那套缰绳、鞍具和车架。没有 Harness 的 Agent就像一匹脱缰的马跑得飞快但随时可能冲进沟里。这篇内容我想聊的就是最后一公里这件事一个 Coding Agent 在实验室里效果不错怎么把它调到能在生产环境里稳定交付。涉及的核心概念包括Coding Agent、Harness、Vibe Coding、CodeArts、可观测性。适合正在做 Agent 落地、被效果不稳定折磨的工程师也适合刚接触 Vibe Coding、想知道为什么我的 Agent 老是翻车的开发者。我会尽量把踩过的坑、调优的思路、以及那些文档里不会写的经验讲清楚让你少走弯路。先说结论性的判断生产级 Coding Agent 的调优80% 的功夫花在 Harness 上而不是模型上。这个比例可能因场景而异但方向是对的。下面我拆开讲。2. Harness 到底是什么把模型能力翻译成工程可靠性的那层壳2.1 一个生活化的类比模型是发动机Harness 是整台车很多人第一次听到 Harness 会懵觉得不就是框架吗其实不太一样。框架Framework更多是代码组织方式而 Harness 强调的是对 Agent 行为的约束、引导和观测。用造车打比方大模型是发动机参数越大马力越足但一台能上路的车光有发动机远远不够你还需要变速箱、方向盘、刹车、仪表盘、安全带。Harness 就是这一整套东西。具体到 Coding AgentHarness 通常包含这几块上下文装配层决定给模型看哪些文件、哪些历史、哪些工具说明。这一层直接决定模型看到的世界是否完整、是否被噪声污染。工具调用层模型能调哪些工具读文件、写文件、跑命令、搜代码每个工具的输入输出怎么定义、怎么校验。执行循环层Agent 的思考-行动-观察循环怎么转什么时候停什么时候重试什么时候放弃。安全与权限层哪些操作允许、哪些禁止写操作怎么回滚敏感路径怎么隔离。可观测层每一步的输入输出、耗时、token 消耗、失败原因怎么记录和呈现。你会发现这五层里没有一层是模型本身。这就是为什么我说调优的重心在 Harness——模型是黑盒Harness 是你能完全掌控的白盒。2.2 Harness 和 Agent 的区别别再混着用了热词里有个高频问题harness 和 agent 区别。我用一句话说清楚Agent 是谁在做这件事Harness 是这件事被允许怎么做。Agent 是那个会思考、会决策的主体Harness 是围绕这个主体搭建的运行环境和约束系统。举个具体例子。你让 Agent修复登录接口的空指针异常。Agent 的决策是先读 LoginService.java再读调用方定位到某行没判空然后改代码。而 Harness 负责的是读文件时只给它相关的那几个文件而不是整个仓库改代码前先做一次备份改完之后自动跑一遍单测如果单测挂了把失败信息喂回去让它重试重试超过三次就停下来报警。Agent 负责聪明Harness 负责靠谱。一个聪明的 Agent 配一个糟糕的 Harness结果就是偶尔惊艳经常翻车。2.3 为什么 Vibe Coding 特别依赖 HarnessVibe Coding 的精髓是人少干预、让 Agent 自己飞。但人越少干预对 Harness 的要求就越高。因为人不在回路里兜底了所有的兜底逻辑必须提前写进 Harness。这就像自动驾驶L2 级别你可以随时接管所以系统容错可以低一点但 L4 级别人基本不碰方向盘了那感知、决策、冗余、失效保护每一样都得做到极致。我见过太多团队Vibe Coding 玩得很嗨但 Harness 基本是裸奔状态——没有回滚、没有观测、没有重试策略。结果就是 Agent 偶尔改对了大家欢呼改错了要花半天人工排查整体效率反而比手写还低。Vibe Coding 的上限由模型决定下限由 Harness 决定。生产环境里下限比上限重要得多。3. 上下文装配Agent 效果差一半的锅在这里3.1 塞得越多不等于效果越好新手最容易犯的错是把整个仓库、整个对话历史一股脑塞给模型觉得信息越全越好。实测下来恰恰相反。上下文窗口是有限的塞进去的每一段无关代码都在稀释真正有用的信息还会显著拉高 token 成本和响应延迟。更麻烦的是噪声会让模型分心去关注一些根本不相关的模块。我的经验是上下文装配要遵循**最小充分原则**刚好够模型完成任务不多一行。具体怎么做分三步。第一步基于任务类型确定检索范围。修 bug 和加功能需要的上下文完全不同。修 bug 通常只需要出错文件、直接调用方、相关测试加功能则需要接口定义、数据模型、相似功能的实现参考。这个映射关系最好在 Harness 里做成配置而不是每次靠人临时判断。第二步用符号索引而不是全文检索。现代 IDE 和代码平台比如 CodeArts 这类通常提供符号级的索引能力能快速定位这个函数被谁调用这个类被谁继承。基于符号关系去拉上下文比基于文本相似度去搜精准度高一个量级。第三步做上下文预算控制。给每类信息分配 token 配额比如出错文件全文 调用方签名 测试用例超出配额就按优先级裁剪。这一步能有效防止上下文爆炸。3.2 上下文里必须显式包含的三样东西除了代码本身有三样东西我强烈建议每次都显式塞进上下文它们对效果的提升立竿见影项目约定命名规范、目录结构、错误处理惯例、日志格式。Agent 不知道你们团队的潜规则你不告诉它它就会按自己的习惯写写出来的代码风格和现有代码格格不入。可用的工具清单及用法明确告诉它有哪些工具、每个工具干什么、什么时候用。很多 Agent 效果差是因为它根本不知道自己能调哪些工具只能瞎猜。验收标准这次任务的完成定义是什么是单测通过是编译通过还是某个接口返回符合预期标准不明确Agent 就不知道什么时候该停。提示项目约定这部分最好做成一个独立的、可版本管理的文件类似团队规范文档让 Harness 每次自动注入。这样规范更新时所有 Agent 任务同步生效不用逐个改 prompt。3.3 一个真实的翻车案例之前有个任务让 Agent 给一个订单模块加超时自动取消功能。第一次跑Agent 写出来的代码逻辑没问题但用了一个团队早就废弃的定时任务框架。原因很简单仓库里还留着几个老文件用了那个框架Agent 检索时把它们当成了参考范例。后来我们在 Harness 里加了一条规则检索上下文时排除标记为 deprecated 的目录。同时把当前推荐使用的技术栈显式写进项目约定。改完之后同类问题再没出现过。这个坑的教训是Agent 会模仿它看到的一切包括你不希望它模仿的东西。上下文装配不只是给够信息更是过滤掉错误示范。4. 执行循环与工具调用让 Agent 学会停下来和重来4.1 循环失控是生产环境第一大杀手Agent 的执行循环如果没设计好会出现两种极端一种是过早停止任务没做完就以为完成了另一种是无限循环在一个错误里反复打转烧掉大量 token 和时间。生产环境里后者更致命因为它会悄无声息地消耗资源。我的做法是给循环设三道闸步数上限单次任务最多执行 N 步比如 30 步超过就强制停止并上报。这个 N 要根据任务复杂度调简单任务 10 步够了复杂重构可能要给到 50 步。无进展检测如果连续几步的观察结果高度相似比如反复读到同一个报错判定为卡住触发策略切换或直接停止。成本上限单次任务的 token 消耗或工具调用次数设一个硬上限超了就停。这一条在多人共用的平台上尤其重要防止某个失控任务拖垮整个配额。4.2 工具设计少而精语义清晰工具不是越多越好。工具太多模型选择困难容易调错工具太少能力受限。我的经验是Coding Agent 的核心工具控制在 6 到 8 个就够工具作用关键设计点读文件获取文件内容支持按行范围读避免大文件全量读写文件修改或新建文件写前自动备份支持 diff 预览搜索按符号或文本检索返回结果带上下文行号执行命令跑测试、编译、lint白名单机制危险命令拦截查看差异看当前改动便于 Agent 自我检查回滚撤销改动一键恢复到某个检查点每个工具的描述文字要写得极其清楚包括什么时候用、输入格式、返回什么、有什么副作用。我见过效果提升最明显的一次改动就是把写文件工具的描述从写入文件内容改成覆盖写入指定文件的指定行范围写入前会自动备份原内容如果文件不存在则创建。描述一清楚Agent 调错的概率大幅下降。4.3 重试策略不是简单重来而是带着信息重来Agent 失败后重试如果只是原样再跑一遍大概率还是失败。有效的重试必须把失败信息喂回去。比如单测挂了要把失败的用例名、断言信息、堆栈一起塞进下一轮的上下文让 Agent 知道上次错在哪。更进一步可以设计分级重试第一次失败原样重试第二次失败换一种策略比如让它先解释问题再动手第三次失败缩小任务范围把大任务拆成小任务三次都失败停下来交给人。这套机制能显著提升 Agent 的自愈率减少人工介入。注意重试一定要有次数上限并且每次重试都要记录日志。否则一旦进入失败-重试-再失败的循环排查起来会非常痛苦。5. 可观测性没有观测的调优都是盲人摸象5.1 为什么可观测性是调优的前提调优的本质是发现问题-定位原因-验证改进。如果连 Agent 每一步在干什么都看不到调优就无从谈起。可观测性要解决三个问题发生了什么、为什么发生、影响多大。具体到 Coding Agent我建议至少记录这几类数据每步的输入输出模型看到了什么、输出了什么、调用了哪个工具、工具返回了什么。关键指标每步耗时、token 消耗、工具调用成功率、任务整体成功率。失败归因失败时记录失败类型上下文不足、工具报错、逻辑错误、超时等便于统计哪类问题最高频。轨迹回放能完整回放一次任务的执行过程用于事后复盘。5.2 用数据驱动调优而不是凭感觉有了观测数据调优就从我觉得变成了数据显示。举个例子我们曾经统计过一批失败任务发现超过 40% 的失败集中在工具调用参数格式错误。这个发现直接指向了工具描述不够清晰的问题改完之后失败率明显下降。再比如通过统计每类任务的步数分布我们发现代码重构类任务的平均步数远高于预期说明这类任务的上下文装配或任务拆解有问题。顺着这条线索排查果然发现重构任务需要的依赖关系图没有被正确注入。没有观测数据你只能看到Agent 又失败了有了观测数据你能看到Agent 在第 7 步因为读不到某个文件而失败。这两者的调优效率天差地别。5.3 观测本身也要控制成本可观测性不是把什么都记下来。全量记录会产生海量日志存储和检索成本都很高。我的做法是分层记录关键节点任务开始、工具调用、任务结束、失败全量记录中间过程模型的思考文本采样记录或只记摘要。这样既保证了可追溯性又控制了成本。6. 安全与回滚生产环境的最后一道防线6.1 权限最小化原则Agent 能做的事越多风险越大。生产环境里我坚持权限最小化Agent 默认只有读权限写权限要按任务临时授予且限定在特定目录。执行命令要过白名单像删除文件、修改系统配置这类操作一律拦截。有人会觉得这样束手束脚影响 Agent 发挥。但我的观点是生产环境里可控比强大重要。一个只能改指定目录、只能跑指定命令的 Agent虽然能力受限但至少不会把整个仓库搞乱。6.2 回滚机制让改错了不再是灾难回滚是 Harness 里最容易被忽视、但最不能省的一环。我的建议是每个写操作前都做检查点Agent 可以随时回滚到任意一个检查点。这样即使它改错了也能一键恢复而不是靠人工一个个文件去比对。回滚机制还有个隐性好处它让 Agent 敢于尝试。知道改错了能回滚Agent 在探索性任务上会更主动效果反而更好。6.3 敏感信息隔离代码仓库里难免有敏感信息密钥、配置、内部地址。Harness 要在上下文装配阶段就把这些内容过滤掉不能让它们进入模型的上下文。同时Agent 的输出也要做检查防止它把敏感信息写进代码或日志。这一条是红线不能有任何侥幸。7. 落地调优的实操节奏先稳后快先窄后宽7.1 别一上来就追求全自动很多团队落地 Coding Agent 时恨不得第一天就全自动。我的建议恰恰相反先做人在回路的半自动跑稳了再逐步放开。具体分三个阶段第一阶段Agent 只读不写。让它分析代码、定位问题、给出修改建议但改动由人来执行。这个阶段主要验证 Agent 的理解能力和建议质量。第二阶段Agent 写但人审。让它直接改代码但每次改动都要人确认。这个阶段验证 Harness 的写操作、回滚、观测是否可靠。第三阶段Agent 自主执行人只处理异常。前两个阶段跑稳了才进入这个阶段。这时候 Harness 的兜底能力必须已经经过充分验证。7.2 从高频、低风险的任务切入不要一上来就让 Agent 干最难的活。从高频、低风险、验收标准明确的任务切入比如补单元测试、修简单的 lint 问题、格式化代码、更新文档注释。这些任务成功率高能快速积累信心和数据也能帮你把 Harness 的基础设施打磨扎实。等这些任务稳定了再逐步扩展到中等复杂度的任务比如小范围重构、bug 修复。高风险的架构级改动建议长期保留人工主导。7.3 建立反馈闭环调优不是一次性的而是持续的。我建议建立一个简单的反馈闭环每次 Agent 任务结束后记录结果成功/失败/需人工修正定期复盘失败案例把共性问题转化为 Harness 的改进项。这个闭环转起来Agent 的效果会持续提升而不是停在某个水平。8. 几个反复踩到的坑和对应的解法8.1 坑一把模型能力当成唯一变量最常见的误区。效果不好就想着换更大的模型结果换了之后发现提升有限。真相是在 Harness 没调好之前换模型的收益很小。先把上下文、工具、循环、观测这些基础设施做扎实再考虑模型升级性价比高得多。8.2 坑二忽视 token 成本Vibe Coding 很容易让人忽略成本。一个任务跑几十步每步都塞大量上下文token 消耗会非常惊人。我的做法是给每个任务设 token 预算并在观测面板里实时显示消耗。成本可见了优化才有动力。8.3 坑三没有版本化 Harness 配置Harness 的配置上下文规则、工具定义、重试策略如果散落在代码各处改起来会非常痛苦而且容易改出不一致。建议把 Harness 配置集中管理、版本化每次调整都有记录、可回滚。这样调优过程本身也是可追溯的。8.4 坑四忽略任务拆解复杂任务直接丢给 Agent成功率往往很低。有效的做法是在 Harness 里做任务拆解把大任务拆成若干子任务逐个执行每个子任务有独立的验收标准。这样不仅成功率高失败时也容易定位是哪一步出了问题。9. 关于效果调优我个人的几点体会调了这么多轮我最大的体会是Coding Agent 的调优本质上是在做预期管理和边界设计。你要清楚地知道 Agent 擅长什么、不擅长什么然后通过 Harness 把它的能力框在擅长的范围内把不擅长的部分交给人或交给其他工具。另一个体会是可观测性投入永远不亏。前期花时间把日志、指标、回放做起来后期调优会轻松很多。反过来如果一开始图省事不做观测后面每次出问题都要靠猜效率极低。最后分享一个小技巧把每次调优的假设和结果记下来。比如我猜失败是因为上下文不足于是增加了依赖注入结果成功率从 60% 提到 75%。这种记录积累多了你会形成一套自己的调优直觉下次遇到类似问题能快速定位。这比任何文档都管用。生产级 Coding Agent 没有银弹它是一堆细节堆出来的可靠性。模型在进步Harness 的工程实践也在成熟但核心逻辑不会变让 Agent 在清晰的边界内做它擅长的事并且每一步都可观测、可回滚、可干预。把这条做到位Vibe Coding 的最后一公里其实没那么难走。 
长河君 · 2026/10/7 12:27:11 · 阅读 1.2k 生产级Coding Agent调优：Harness工程实践与可观测性落地
1. 从能跑通到敢上线生产级 Coding Agent 的真实鸿沟Vibe Coding 这个词这两年被聊得很多大意是用自然语言把意图丢给 Coding Agent让它自己读代码、改代码、跑测试人只负责感觉对不对。Demo 阶段确实爽一个 prompt 下去几十行代码就出来了。但真正把它放进生产环境、接进企业级研发流水线之后你会发现一个很尴尬的事实能跑通和敢上线之间隔着一条比想象中宽得多的沟。我自己参与过几轮 Coding Agent 的落地调优最大的感受是——模型能力只是入场券真正决定成败的是模型外面那一圈东西。圈内现在有个词叫Harness直译是马具、挽具非常形象模型是那匹有劲但方向不定的马Harness 就是套在它身上、把它的力气导向正确方向的那套缰绳、鞍具和车架。没有 Harness 的 Agent就像一匹脱缰的马跑得飞快但随时可能冲进沟里。这篇内容我想聊的就是最后一公里这件事一个 Coding Agent 在实验室里效果不错怎么把它调到能在生产环境里稳定交付。涉及的核心概念包括Coding Agent、Harness、Vibe Coding、CodeArts、可观测性。适合正在做 Agent 落地、被效果不稳定折磨的工程师也适合刚接触 Vibe Coding、想知道为什么我的 Agent 老是翻车的开发者。我会尽量把踩过的坑、调优的思路、以及那些文档里不会写的经验讲清楚让你少走弯路。先说结论性的判断生产级 Coding Agent 的调优80% 的功夫花在 Harness 上而不是模型上。这个比例可能因场景而异但方向是对的。下面我拆开讲。2. Harness 到底是什么把模型能力翻译成工程可靠性的那层壳2.1 一个生活化的类比模型是发动机Harness 是整台车很多人第一次听到 Harness 会懵觉得不就是框架吗其实不太一样。框架Framework更多是代码组织方式而 Harness 强调的是对 Agent 行为的约束、引导和观测。用造车打比方大模型是发动机参数越大马力越足但一台能上路的车光有发动机远远不够你还需要变速箱、方向盘、刹车、仪表盘、安全带。Harness 就是这一整套东西。具体到 Coding AgentHarness 通常包含这几块上下文装配层决定给模型看哪些文件、哪些历史、哪些工具说明。这一层直接决定模型看到的世界是否完整、是否被噪声污染。工具调用层模型能调哪些工具读文件、写文件、跑命令、搜代码每个工具的输入输出怎么定义、怎么校验。执行循环层Agent 的思考-行动-观察循环怎么转什么时候停什么时候重试什么时候放弃。安全与权限层哪些操作允许、哪些禁止写操作怎么回滚敏感路径怎么隔离。可观测层每一步的输入输出、耗时、token 消耗、失败原因怎么记录和呈现。你会发现这五层里没有一层是模型本身。这就是为什么我说调优的重心在 Harness——模型是黑盒Harness 是你能完全掌控的白盒。2.2 Harness 和 Agent 的区别别再混着用了热词里有个高频问题harness 和 agent 区别。我用一句话说清楚Agent 是谁在做这件事Harness 是这件事被允许怎么做。Agent 是那个会思考、会决策的主体Harness 是围绕这个主体搭建的运行环境和约束系统。举个具体例子。你让 Agent修复登录接口的空指针异常。Agent 的决策是先读 LoginService.java再读调用方定位到某行没判空然后改代码。而 Harness 负责的是读文件时只给它相关的那几个文件而不是整个仓库改代码前先做一次备份改完之后自动跑一遍单测如果单测挂了把失败信息喂回去让它重试重试超过三次就停下来报警。Agent 负责聪明Harness 负责靠谱。一个聪明的 Agent 配一个糟糕的 Harness结果就是偶尔惊艳经常翻车。2.3 为什么 Vibe Coding 特别依赖 HarnessVibe Coding 的精髓是人少干预、让 Agent 自己飞。但人越少干预对 Harness 的要求就越高。因为人不在回路里兜底了所有的兜底逻辑必须提前写进 Harness。这就像自动驾驶L2 级别你可以随时接管所以系统容错可以低一点但 L4 级别人基本不碰方向盘了那感知、决策、冗余、失效保护每一样都得做到极致。我见过太多团队Vibe Coding 玩得很嗨但 Harness 基本是裸奔状态——没有回滚、没有观测、没有重试策略。结果就是 Agent 偶尔改对了大家欢呼改错了要花半天人工排查整体效率反而比手写还低。Vibe Coding 的上限由模型决定下限由 Harness 决定。生产环境里下限比上限重要得多。3. 上下文装配Agent 效果差一半的锅在这里3.1 塞得越多不等于效果越好新手最容易犯的错是把整个仓库、整个对话历史一股脑塞给模型觉得信息越全越好。实测下来恰恰相反。上下文窗口是有限的塞进去的每一段无关代码都在稀释真正有用的信息还会显著拉高 token 成本和响应延迟。更麻烦的是噪声会让模型分心去关注一些根本不相关的模块。我的经验是上下文装配要遵循**最小充分原则**刚好够模型完成任务不多一行。具体怎么做分三步。第一步基于任务类型确定检索范围。修 bug 和加功能需要的上下文完全不同。修 bug 通常只需要出错文件、直接调用方、相关测试加功能则需要接口定义、数据模型、相似功能的实现参考。这个映射关系最好在 Harness 里做成配置而不是每次靠人临时判断。第二步用符号索引而不是全文检索。现代 IDE 和代码平台比如 CodeArts 这类通常提供符号级的索引能力能快速定位这个函数被谁调用这个类被谁继承。基于符号关系去拉上下文比基于文本相似度去搜精准度高一个量级。第三步做上下文预算控制。给每类信息分配 token 配额比如出错文件全文 调用方签名 测试用例超出配额就按优先级裁剪。这一步能有效防止上下文爆炸。3.2 上下文里必须显式包含的三样东西除了代码本身有三样东西我强烈建议每次都显式塞进上下文它们对效果的提升立竿见影项目约定命名规范、目录结构、错误处理惯例、日志格式。Agent 不知道你们团队的潜规则你不告诉它它就会按自己的习惯写写出来的代码风格和现有代码格格不入。可用的工具清单及用法明确告诉它有哪些工具、每个工具干什么、什么时候用。很多 Agent 效果差是因为它根本不知道自己能调哪些工具只能瞎猜。验收标准这次任务的完成定义是什么是单测通过是编译通过还是某个接口返回符合预期标准不明确Agent 就不知道什么时候该停。提示项目约定这部分最好做成一个独立的、可版本管理的文件类似团队规范文档让 Harness 每次自动注入。这样规范更新时所有 Agent 任务同步生效不用逐个改 prompt。3.3 一个真实的翻车案例之前有个任务让 Agent 给一个订单模块加超时自动取消功能。第一次跑Agent 写出来的代码逻辑没问题但用了一个团队早就废弃的定时任务框架。原因很简单仓库里还留着几个老文件用了那个框架Agent 检索时把它们当成了参考范例。后来我们在 Harness 里加了一条规则检索上下文时排除标记为 deprecated 的目录。同时把当前推荐使用的技术栈显式写进项目约定。改完之后同类问题再没出现过。这个坑的教训是Agent 会模仿它看到的一切包括你不希望它模仿的东西。上下文装配不只是给够信息更是过滤掉错误示范。4. 执行循环与工具调用让 Agent 学会停下来和重来4.1 循环失控是生产环境第一大杀手Agent 的执行循环如果没设计好会出现两种极端一种是过早停止任务没做完就以为完成了另一种是无限循环在一个错误里反复打转烧掉大量 token 和时间。生产环境里后者更致命因为它会悄无声息地消耗资源。我的做法是给循环设三道闸步数上限单次任务最多执行 N 步比如 30 步超过就强制停止并上报。这个 N 要根据任务复杂度调简单任务 10 步够了复杂重构可能要给到 50 步。无进展检测如果连续几步的观察结果高度相似比如反复读到同一个报错判定为卡住触发策略切换或直接停止。成本上限单次任务的 token 消耗或工具调用次数设一个硬上限超了就停。这一条在多人共用的平台上尤其重要防止某个失控任务拖垮整个配额。4.2 工具设计少而精语义清晰工具不是越多越好。工具太多模型选择困难容易调错工具太少能力受限。我的经验是Coding Agent 的核心工具控制在 6 到 8 个就够工具作用关键设计点读文件获取文件内容支持按行范围读避免大文件全量读写文件修改或新建文件写前自动备份支持 diff 预览搜索按符号或文本检索返回结果带上下文行号执行命令跑测试、编译、lint白名单机制危险命令拦截查看差异看当前改动便于 Agent 自我检查回滚撤销改动一键恢复到某个检查点每个工具的描述文字要写得极其清楚包括什么时候用、输入格式、返回什么、有什么副作用。我见过效果提升最明显的一次改动就是把写文件工具的描述从写入文件内容改成覆盖写入指定文件的指定行范围写入前会自动备份原内容如果文件不存在则创建。描述一清楚Agent 调错的概率大幅下降。4.3 重试策略不是简单重来而是带着信息重来Agent 失败后重试如果只是原样再跑一遍大概率还是失败。有效的重试必须把失败信息喂回去。比如单测挂了要把失败的用例名、断言信息、堆栈一起塞进下一轮的上下文让 Agent 知道上次错在哪。更进一步可以设计分级重试第一次失败原样重试第二次失败换一种策略比如让它先解释问题再动手第三次失败缩小任务范围把大任务拆成小任务三次都失败停下来交给人。这套机制能显著提升 Agent 的自愈率减少人工介入。注意重试一定要有次数上限并且每次重试都要记录日志。否则一旦进入失败-重试-再失败的循环排查起来会非常痛苦。5. 可观测性没有观测的调优都是盲人摸象5.1 为什么可观测性是调优的前提调优的本质是发现问题-定位原因-验证改进。如果连 Agent 每一步在干什么都看不到调优就无从谈起。可观测性要解决三个问题发生了什么、为什么发生、影响多大。具体到 Coding Agent我建议至少记录这几类数据每步的输入输出模型看到了什么、输出了什么、调用了哪个工具、工具返回了什么。关键指标每步耗时、token 消耗、工具调用成功率、任务整体成功率。失败归因失败时记录失败类型上下文不足、工具报错、逻辑错误、超时等便于统计哪类问题最高频。轨迹回放能完整回放一次任务的执行过程用于事后复盘。5.2 用数据驱动调优而不是凭感觉有了观测数据调优就从我觉得变成了数据显示。举个例子我们曾经统计过一批失败任务发现超过 40% 的失败集中在工具调用参数格式错误。这个发现直接指向了工具描述不够清晰的问题改完之后失败率明显下降。再比如通过统计每类任务的步数分布我们发现代码重构类任务的平均步数远高于预期说明这类任务的上下文装配或任务拆解有问题。顺着这条线索排查果然发现重构任务需要的依赖关系图没有被正确注入。没有观测数据你只能看到Agent 又失败了有了观测数据你能看到Agent 在第 7 步因为读不到某个文件而失败。这两者的调优效率天差地别。5.3 观测本身也要控制成本可观测性不是把什么都记下来。全量记录会产生海量日志存储和检索成本都很高。我的做法是分层记录关键节点任务开始、工具调用、任务结束、失败全量记录中间过程模型的思考文本采样记录或只记摘要。这样既保证了可追溯性又控制了成本。6. 安全与回滚生产环境的最后一道防线6.1 权限最小化原则Agent 能做的事越多风险越大。生产环境里我坚持权限最小化Agent 默认只有读权限写权限要按任务临时授予且限定在特定目录。执行命令要过白名单像删除文件、修改系统配置这类操作一律拦截。有人会觉得这样束手束脚影响 Agent 发挥。但我的观点是生产环境里可控比强大重要。一个只能改指定目录、只能跑指定命令的 Agent虽然能力受限但至少不会把整个仓库搞乱。6.2 回滚机制让改错了不再是灾难回滚是 Harness 里最容易被忽视、但最不能省的一环。我的建议是每个写操作前都做检查点Agent 可以随时回滚到任意一个检查点。这样即使它改错了也能一键恢复而不是靠人工一个个文件去比对。回滚机制还有个隐性好处它让 Agent 敢于尝试。知道改错了能回滚Agent 在探索性任务上会更主动效果反而更好。6.3 敏感信息隔离代码仓库里难免有敏感信息密钥、配置、内部地址。Harness 要在上下文装配阶段就把这些内容过滤掉不能让它们进入模型的上下文。同时Agent 的输出也要做检查防止它把敏感信息写进代码或日志。这一条是红线不能有任何侥幸。7. 落地调优的实操节奏先稳后快先窄后宽7.1 别一上来就追求全自动很多团队落地 Coding Agent 时恨不得第一天就全自动。我的建议恰恰相反先做人在回路的半自动跑稳了再逐步放开。具体分三个阶段第一阶段Agent 只读不写。让它分析代码、定位问题、给出修改建议但改动由人来执行。这个阶段主要验证 Agent 的理解能力和建议质量。第二阶段Agent 写但人审。让它直接改代码但每次改动都要人确认。这个阶段验证 Harness 的写操作、回滚、观测是否可靠。第三阶段Agent 自主执行人只处理异常。前两个阶段跑稳了才进入这个阶段。这时候 Harness 的兜底能力必须已经经过充分验证。7.2 从高频、低风险的任务切入不要一上来就让 Agent 干最难的活。从高频、低风险、验收标准明确的任务切入比如补单元测试、修简单的 lint 问题、格式化代码、更新文档注释。这些任务成功率高能快速积累信心和数据也能帮你把 Harness 的基础设施打磨扎实。等这些任务稳定了再逐步扩展到中等复杂度的任务比如小范围重构、bug 修复。高风险的架构级改动建议长期保留人工主导。7.3 建立反馈闭环调优不是一次性的而是持续的。我建议建立一个简单的反馈闭环每次 Agent 任务结束后记录结果成功/失败/需人工修正定期复盘失败案例把共性问题转化为 Harness 的改进项。这个闭环转起来Agent 的效果会持续提升而不是停在某个水平。8. 几个反复踩到的坑和对应的解法8.1 坑一把模型能力当成唯一变量最常见的误区。效果不好就想着换更大的模型结果换了之后发现提升有限。真相是在 Harness 没调好之前换模型的收益很小。先把上下文、工具、循环、观测这些基础设施做扎实再考虑模型升级性价比高得多。8.2 坑二忽视 token 成本Vibe Coding 很容易让人忽略成本。一个任务跑几十步每步都塞大量上下文token 消耗会非常惊人。我的做法是给每个任务设 token 预算并在观测面板里实时显示消耗。成本可见了优化才有动力。8.3 坑三没有版本化 Harness 配置Harness 的配置上下文规则、工具定义、重试策略如果散落在代码各处改起来会非常痛苦而且容易改出不一致。建议把 Harness 配置集中管理、版本化每次调整都有记录、可回滚。这样调优过程本身也是可追溯的。8.4 坑四忽略任务拆解复杂任务直接丢给 Agent成功率往往很低。有效的做法是在 Harness 里做任务拆解把大任务拆成若干子任务逐个执行每个子任务有独立的验收标准。这样不仅成功率高失败时也容易定位是哪一步出了问题。9. 关于效果调优我个人的几点体会调了这么多轮我最大的体会是Coding Agent 的调优本质上是在做预期管理和边界设计。你要清楚地知道 Agent 擅长什么、不擅长什么然后通过 Harness 把它的能力框在擅长的范围内把不擅长的部分交给人或交给其他工具。另一个体会是可观测性投入永远不亏。前期花时间把日志、指标、回放做起来后期调优会轻松很多。反过来如果一开始图省事不做观测后面每次出问题都要靠猜效率极低。最后分享一个小技巧把每次调优的假设和结果记下来。比如我猜失败是因为上下文不足于是增加了依赖注入结果成功率从 60% 提到 75%。这种记录积累多了你会形成一套自己的调优直觉下次遇到类似问题能快速定位。这比任何文档都管用。生产级 Coding Agent 没有银弹它是一堆细节堆出来的可靠性。模型在进步Harness 的工程实践也在成熟但核心逻辑不会变让 Agent 在清晰的边界内做它擅长的事并且每一步都可观测、可回滚、可干预。把这条做到位Vibe Coding 的最后一公里其实没那么难走。