编码代理支撑框架：如何用前馈、反馈和传感器提升 AI 编程质量

随着 AI 编程工具和编码代理的普及，工程团队开始面临一个新的问题：如何让编码代理稳定地产出高质量代码，而不是把所有风险都留给人工审核？本文讨论的核心，就是如何为编码代理构建一套工程化支撑框架，通过前馈控制、反馈回路、自动化传感器和人工监督，提升代码质量、减少返工，并增强团队对代理输出的信心。

在人工智能代理的讨论中，harness 一词已经逐渐成为一个泛称，用来指代模型之外支撑代理运行的所有组件。也就是说：

代理 = 模型 + 支撑框架

这个定义非常宽泛，因此有必要针对不同类型的代理进一步细化。本文想尝试在编码代理这一具体语境下，讨论 harness 究竟意味着什么。

对于编码代理而言，部分支撑能力已经内置在系统中，例如系统提示词、特定的代码检索机制，甚至更复杂的任务编排系统。但与此同时，编码代理也为用户提供了许多能力，使我们能够围绕自己的业务场景、代码库和工程体系，构建外部的定制化支撑框架。

图 1：术语“harness”根据上下文的不同而有不同的含义。

一个设计良好的编码代理支撑框架通常有两个目标：第一，提高代理首次执行正确操作的概率；第二，建立反馈回路，使问题在进入人工审核之前尽可能被代理自行发现并修正。最终，它应该减少人工审核负担，提高系统质量，同时降低无效 token 消耗。

前馈与反馈：编码代理质量控制的基础

要有效驾驭编码代理，我们既需要预测不希望出现的输出，并在事前加以约束；也需要布置“传感器”，让代理在行动之后能够观察结果并自我纠正。

引导机制，也就是前馈控制，用于预测代理可能采取的行为，并在其行动之前施加引导。好的引导机制能够提高代理第一次尝试就产出高质量结果的概率。

传感器机制，也就是反馈控制，用于在代理执行操作之后观察结果，并帮助它进行自我纠正。当这些传感器生成的信号专门面向 LLM 处理进行优化时，效果会尤其明显。例如，自定义代码检查器不仅指出问题，还附带面向代理的修正指令，这本质上就是一种有益的提示注入。

二者缺一不可。只有反馈，代理可能不断重复同类错误；只有前馈，代理虽然知道规则，却无法判断这些规则是否真的奏效。

计算型推理与模型推理

引导机制和传感器机制可以进一步分为两类。

第一类是计算型控制。这类控制通常确定性强、速度快，由 CPU 执行。典型例子包括测试、代码检查、类型检查和结构分析。它们通常可以在几毫秒到几秒内完成，结果也相对可靠。

第二类是模型推理型控制。这类控制包括语义分析、AI 代码审查、“让 LLM 充当裁判”等。它们通常依赖 GPU 或 NPU，速度更慢，成本更高，结果也更不确定。

计算型引导可以提高确定性工具获得良好结果的概率。计算型传感器成本低、速度快，足以在代理每次修改代码后运行。模型推理型控制虽然更昂贵，也更不确定，但它能够提供更丰富的指导，并补充额外的语义判断。尽管模型推理型传感器不具备确定性，但当它与强模型，或者更准确地说，与适合当前任务的模型结合使用时，仍然可以显著增强我们对结果的信心。

编码代理支撑框架的典型示例

控制对象	方向	控制类型	示例实现
编码规范	前馈	模型推理型	AGENTS.md、Skills
新项目启动引导	前馈	两者兼有	详细指令与初始化脚本
代码修改	前馈	计算型	可访问自动化重构规则的工具
结构测试	反馈	计算型	pre-commit 钩子或编码代理钩子运行架构测试，检查是否违反模块边界
审查指南	反馈	模型推理型	Skills

调节循环：持续优化编码代理的行为

在这一过程中，人的任务是通过持续迭代优化控制系统来引导代理。当某类问题反复出现时，我们就应该改进前馈和反馈控制，降低它未来再次发生的概率，甚至彻底消除此类问题。

在控制回路中，我们当然也可以利用 AI 来改进系统本身。如今，借助编码代理，构建更多自定义控制机制和自定义静态分析的成本已经大幅降低。代理可以帮助我们编写结构测试，根据观察到的模式生成规则草案，搭建自定义代码检查器，或者通过分析历史代码创建操作指南。

时机：如何守住代码质量

持续集成团队长期面临一个挑战：如何根据成本、速度和关键性，将测试、检查和人工评审合理分布在开发周期中。理想情况下，如果追求持续交付，我们甚至希望每一次提交都处于可部署状态。问题发现得越早，修复成本就越低，因此我们希望尽可能早地把检查前置到生产环境之前。

反馈机制，包括新型的模型推理型反馈机制，也需要相应地分布在整个生命周期中。对于企业团队而言，这些控制机制不应只停留在代码仓库或单个工具里，还需要贯穿需求、开发、测试、发布和知识沉淀全过程。以 PingCode 这类智能化研发管理工具为例，它能够将团队目标、客户反馈、需求清理、评审排期、项目开发、测试发布和 Wiki 知识积累串联起来，并打通研发工具链，让编码代理产生的信号、规则和经验更容易沉淀为可持续复用的研发资产。

变更生命周期中的前馈与反馈

哪些工具速度足够快，应该在集成之前，甚至在提交之前运行？例如代码检查器、快速测试套件、基础代码审查代理。

哪些工具成本更高，适合在流程集成之后运行，同时继续重复执行较快的控制机制？例如变异测试，或者能够基于全局上下文进行更广泛判断的代码审查。

持续漂移与健康传感器

哪些类型的漂移会逐渐积累，需要通过持续运行的传感器在整个代码库中监控，而不应只局限于单次变更生命周期？例如死代码检测、测试覆盖率质量分析、依赖扫描器。

代理可以监控哪些运行时反馈？例如，让它们查找服务级别目标（SLO）下降的情况并提出改进建议；或者让 AI 裁判持续抽样评估响应质量，并标记日志中的异常模式。

治理类别：支撑框架需要调节什么

代理支撑框架的作用类似于控制论中的调速器。它结合前馈和反馈机制，将代码库调节到期望状态。

区分“期望状态”的不同维度很有用，因为这些维度对应着支撑框架需要调节的不同内容。不同类别的可治理性和复杂度并不相同。只有把类别划分清楚，我们才能把“支撑框架”这个原本非常宽泛的概念描述得更加精确。

目前，我认为以下三个类别比较有用。

可维护性：最容易落地的编码代理治理方向

本文中的大多数例子都与内部代码质量和可维护性有关。目前，这是最容易落地的一类治理方式，因为我们已经有大量现成工具可以利用。

为了反思上述可维护性治理理念在多大程度上增强了我对代理的信任，我将之前记录的常见编码代理故障模式与这些理念进行了对照。

计算型传感器能够可靠捕捉结构性问题，例如重复代码、圈复杂度过高、测试覆盖率不足、架构漂移、风格违规等。这些方法成本低、经过验证，并且结果确定。

LLM 可以部分处理需要语义判断的问题，例如语义重复的代码、冗余测试、粗暴修复和过度设计的解决方案。但这类方法成本高、具有概率性，也不适合在每次提交时都运行。

然而，两者都无法可靠发现一些影响更大的问题，例如误诊、过度设计、不必要的功能，以及对指令的误解。它们有时能够发现这些问题，但可靠性还不足以显著减少人工监督。如果用户一开始没有明确说明需求，那么任何传感器都没有足够依据判断正确性。

架构适应度函数

这一组引导机制和传感器用于定义并检查应用程序的架构特征。简而言之，它们就是架构适应度函数。

例如，Skills 可以记录我们的性能要求，而性能测试可以向代理反馈其修改究竟提升了性能还是降低了性能。

再比如，Skills 可以描述用于提升可观测性的编码规范，例如日志记录标准；调试说明则可以要求代理反思当前日志质量是否足以支持问题定位。

行为框架：如何判断功能是否符合预期

这是一个显而易见却很难处理的问题：我们如何引导并感知应用程序的功能行为是否符合预期？

目前，我发现大多数赋予编码代理较高自主权的人，通常采用以下方式。

前馈方面，提供功能规范。规范的详细程度不一，可能只是一个简短提示，也可能是多文件规格说明。

反馈方面，检查 AI 生成的测试套件是否通过，覆盖率是否足够高。有些人还会使用变异测试来监控测试质量。然后，再将这些结果与人工测试结合起来。

这种方法过于依赖 AI 生成的测试，而这显然还远远不够。我的一些同事在使用经过批准的测试场景方面取得了不错的效果，但这种方案在某些领域比其他领域更容易应用。他们会根据具体情况选择性使用，不过这并不能彻底解决测试质量问题。

总体来看，我们仍然需要投入大量工作，才能找到良好的功能行为框架，以真正增强信心、减少监督和手动测试。

可治理性：并非所有代码库都适合代理治理

并非所有代码库都同样适合被支撑框架治理。强类型语言编写的代码库天然具备类型检查机制；清晰定义的模块边界能够提供架构约束规则；成熟应用框架会抽象掉代理无需关心的细节，从而隐式提高代理成功的概率。缺少这些特性时，许多控制机制就难以建立。

新建项目和遗留项目面临的情况也截然不同。新建团队可以从一开始就将可维护性纳入设计之中。技术决策和架构选择会直接决定代码库的可治理性。而遗留项目团队，尤其是维护大量技术债务应用的团队，则面临更严峻的挑战：最需要可维护性治理的地方，往往也是最难建立治理机制的地方。

支撑框架模板

大多数企业都有一些常见的服务拓扑结构，可以覆盖 80% 的需求，例如通过 API 暴露数据的业务服务、事件处理服务和数据仪表盘。在许多成熟的工程组织中，这些拓扑结构已经被编码为服务模板。

未来，这些模板可能会演变为支撑框架模板：一套引导机制和传感器，用于将编码代理约束在特定拓扑结构、约定和技术栈之内。团队甚至可能开始根据现有的支撑框架模板来选择技术栈和架构。

当然，我们也会面临与服务模板类似的挑战。一旦团队实例化这些模板，它们就会开始逐渐偏离上游改进。支撑框架模板也会遇到同样的版本控制和贡献问题，而且由于其中包含难以测试的非确定性引导机制和传感器，问题可能更加复杂。

人类在编码代理治理中的角色

作为开发者，我们自然而然地将自身技能和经验融入每个代码库。我们吸收各种约定和最佳实践，体会过复杂性带来的认知压力，也清楚自己的名字会出现在提交记录中。

此外，我们还具备组织协作意识：了解团队目标，知道哪些技术债务因业务原因可以被容忍，也知道在特定情境下“优秀”究竟意味着什么。我们循序渐进，按照自己的节奏推进工作，这为经验的积累和运用留下了思考空间。

编码代理完全不具备这些能力。它没有社会责任感，不会对一个 300 行函数产生审美上的反感，也没有“我们这里不这么做”的直觉，更没有组织记忆。它不知道哪些惯例真正重要，哪些只是习惯；也不知道一个技术上正确的解决方案是否符合团队目标。

支撑框架的目的，是将人类开发者的经验外化并显式化，但它的作用也有边界。构建一套连贯的引导机制、传感器和自我纠错循环成本很高，因此我们必须明确目标并区分优先级。一个好的支撑框架不应试图完全消除人工干预，而应将人工干预引导到最关键的地方。

一个起点，以及一些尚未解决的问题

本文提出的思维模型描述了一些已经在实践中应用的技术，也有助于我们围绕仍需解决的问题展开更有结构的讨论。其目标是将讨论提升到单个功能之上：不只是讨论 Skills 和 MCP 服务器，而是讨论如何战略性地设计一个控制系统，使我们真正能够对代理的产出建立信心。

以下是当前围绕支撑框架展开的一些讨论和实践示例。

海外某些工程团队记录了自己的支撑框架结构：采用分层架构，并通过自定义代码检查器和结构测试强制执行；同时定期进行“垃圾回收”，扫描代码偏差，并让代理提出修复建议。他们的结论是：现在最大的挑战集中在环境、反馈回路和控制系统的设计上。

海外某些公司在介绍其内部助手时提到了一些功能，例如基于启发式方法运行相关代码检查器的推送前钩子。他们强调“左移反馈”的重要性，也展示了如何将反馈传感器集成到代理工作流中。

变异测试和结构测试是计算型反馈传感器的例子。过去它们没有得到充分利用，如今正在重新受到关注。

开发者越来越多地讨论将 LSP 和代码智能集成到编码代理中。这些都是计算型前馈引导机制的例子。

我也从海外某些技术团队那里听到过一些实践案例：他们同时使用计算型传感器和模型推理型传感器来应对架构漂移，例如通过代理与自定义代码检查器的组合提高 API 质量，或者借助“代码清理大军”改善整体代码质量。

仍有许多问题有待解决，前面提到的行为框架只是其中之一。随着支撑框架不断扩展，我们如何保持其一致性，使引导机制和传感器保持同步，避免相互矛盾？当指令和反馈信号指向不同方向时，我们在多大程度上可以信任代理做出合理权衡？如果传感器从未触发，这究竟意味着质量很高，还是意味着检测机制不足？

我们需要一种方法来评估支撑框架的覆盖率和质量，类似于代码覆盖率和变异测试之于测试体系的作用。目前，前馈和反馈控制分散在交付流程的不同阶段，因此，开发能够帮助我们配置、同步和分析这些控制机制的工具，将具有巨大潜力。

构建这种外部支撑框架，正在成为一种持续性的工程实践，而不是一次性的配置工作。