Harness Engineering（六）：Agent 也会复制技术债务

Agent 很擅长沿用代码库中已有的模式。这既能提高实现速度，也会带来长期风险。

如果项目已有清晰的分层、稳定的共享工具和一致的测试方式，Agent 往往会继续遵循这些结构。但如果代码库里同时存在三个相似的 helper、两套日志格式和一批临时绕行方案，它也会把这些写法视为可以照搬的先例。

代码生成得越快，模式传播得也越快。过去，一种不理想的实现也许几个月后才会被复制到第五处；现在，它可能在一周内扩散到几十个文件。

OpenAI 团队早期曾把每周五都用于清理所谓的“AI slop”，相当于拿出 20% 的工作时间处理这些问题。但这种集中清理很快就难以维持。后来，他们把一组明确的“黄金原则”写入代码库，并运行后台 Codex 任务，持续查找偏离原则的代码、更新质量评分并发起范围明确的重构 Pull Request。OpenAI 表示，这些小型清理改动大多能在一分钟内完成审查并自动合并。

官方原文没有严格定义“AI slop”。本文用它指代生成代码在反复模仿不理想先例时，逐渐积累的重复实现、临时补丁和低质量模式。

与其定期突击清理，不如把清理变成持续运行的工程机制。

代码生成越快，技术债务传播得越快

技术债务通常不是突然出现的。一个任务为了赶进度添加了局部 helper；下一个任务发现附近已有类似实现，于是继续复用；几个月后，这种权宜之计就成了大家默认的写法。

Agent 会加速这个过程，因为它经常搜索现有代码来寻找实现参考。某种写法出现得越频繁，就越容易被它判断为项目惯例，无论这个惯例最初是否合理。

因此，面向 Agent 的代码库不能只关注单项改动是否正确，还要观察不良模式是否正在传播：

• 同类工具是否出现多个实现。
• 目录和依赖方向是否逐渐偏离架构。
• 临时兼容逻辑是否开始被新代码依赖。
• 测试是否不断复制脆弱写法。
• 文档是否逐渐偏离代码的实际行为。

这些问题通常不会立即导致构建失败，却会让未来的 Agent 更容易做出错误判断。

黄金原则应该说明代码库要长期保持什么状态

OpenAI 所说的“黄金原则”不是一份不断膨胀的风格指南，而是少数立场明确、能够反复检查的工程规则。

例如：

• 优先复用共享工具，不为同一能力重复创建局部 helper。
• 外部数据必须在边界验证，不能根据猜测的结构继续构建。
• 对外行为通过有明确类型的接口表达。
• 代码和文档中的架构地图必须保持一致。
• 重要质量规则应该进入 lint 或测试，而不是依赖记忆。

一条有用的黄金原则应当回答三个问题：代码库应该保持什么状态？为什么这种状态有利于长期维护？系统如何发现偏离？

主观的风格偏好适合留在代码审查指南中，由人结合具体情况判断。对于能够明确识别、而且反复违反会带来长期成本的规则，则应尽量交给工具自动检查。

其中，“优先使用共享工具”和“在边界验证数据，而不是猜测数据结构”来自 OpenAI 公布的黄金原则。类型接口、架构地图和规则自动化，则是本文根据同一思路补充的落地示例。

频繁的小修复，比周期性大重构更适合 Agent

等技术债务积累到一定规模后再安排大型重构，往往会产生长期分支、大量冲突和昂贵的验证工作。对于仍在持续生成改动的 Agent 系统，这种方式尤其困难。

更合适的做法，是把治理拆成频繁、范围明确的小任务：

扫描一种偏差
  ↓
定位有限范围
  ↓
发起小型重构 PR
  ↓
运行验证并合并
  ↓
把新判断更新到规则或检查

每个治理任务只处理一种明确的问题，例如合并重复 helper、迁移已经弃用的 API、补齐结构化日志字段，或修正过期的文档链接。范围越小，Agent 越容易证明改动不会破坏现有行为，人也越容易快速审查。

这种循环很像垃圾回收：它不要求系统永远不产生技术债务，而是避免问题不断累积，最终拖垮整个代码库。

后台治理任务也需要权限边界和停止条件

不应该只给后台 Agent 一句“让代码库更整洁”，就允许它自由重写大量代码。治理任务同样需要自己的 Harness：

• 每次只处理一种可定义的偏差。
• 限制允许修改的目录和文件数量。
• 要求行为测试在修改前后保持一致。
• 高风险领域只生成建议，不自动合并。
• 无法证明等价时停止并请求人工判断。
• 记录发现、修复、误报和回滚情况。

这些约束可以防止清理工作本身引入新的偏差。Agent 适合处理重复、局部且证据明确的修复；至于架构如何演进、复杂场景如何取舍，仍需由人判断。

质量指标还要反映下一个 Agent 的工作难度

传统代码质量指标通常关注覆盖率、复杂度和缺陷数量。面向 Agent 的系统还需要观察：下一个 Agent 能否高效、正确地理解并修改代码库？

可以逐步记录：

• 同类任务一次通过的比例。
• Agent 因找不到项目规则而请求人工介入的次数。
• 同一种代码审查意见重复出现的频率。
• 重复实现和越界依赖的新增速度。
• 文档与代码不一致的发现数量。
• 自动治理 PR 的误报率和回滚率。

这些指标不必合并成一个看似精确的总分。它们的价值在于发现趋势：随着代码库增长，Agent 是否需要更多尝试才能完成同类任务？如果答案是肯定的，说明代码库可能越来越难以理解，现有约束也可能正在失效。

人仍然决定代码库应该向哪里演进

持续治理并不意味着把维护工作完全交给 Agent。Agent 可以发现重复实现、执行迁移并运行验证，却不能独立决定所有工程取舍。

人仍然要判断哪些模式值得成为标准、哪些例外应该保留，以及哪些局部复杂度是产品需求带来的合理代价。关键变化在于：一旦形成稳定判断，就尽量把它写入文档、工具、测试和治理任务，不必在之后的每个 Pull Request 中重新讨论。

OpenAI 也坦言，团队尚不知道一个完全由 Agent 生成的系统在多年后能否保持架构一致，也仍在寻找最值得投入人类判断的环节，以及模型能力提高后 Harness 应该如何变化。持续治理并不证明长期问题已经解决；它只是提供了一条持续发现问题、修正系统并积累经验的反馈循环。

至此，Harness Engineering 系列形成了一个完整循环：知识让 Agent 找到事实，环境让它观察结果，约束让规则可以执行，审查流程让大量改动能够被及时处理，持续治理则防止系统在高速变化中失去一致性。

模型决定单次执行能有多聪明。Harness 决定在成千上万次执行之后，系统是否仍然可靠、清晰，并且能够继续演进。

本文整理自 OpenAI 的文章 Harness engineering: leveraging Codex in an agent-first world。核心观点与官方案例来自原文，治理权限、停止条件和质量指标是本文的实践延展。

Harness Engineering 系列

• （一）当工程师开始设计 Agent 的工作环境
• （二）给 Agent 一张代码库地图
• （三）让软件运行状态对 Agent 可读
• （四）把工程规则变成可执行约束
• （五）当 Agent 的产出超过人的注意力
• （六）Agent 也会复制技术债务（本文）

相关阅读

• 智能体需要 Harness，不只是更强的模型 —— 系列背后的 Harness 基础定义。
• 生产级 Agent 的评估与监控 —— 让真实失败进入持续改进循环。