Agent Hareness Engineering

Agent 迈入了新时代。

过去，我们利用模型来辅助人类进行编程，在整个软件工程流程中，模型仅仅在编码阶段发挥作用。在这个时期，人类的认知带宽是开发的核心瓶颈。但是在过去一段时间里，模型的 Agent 能力已经显著提升，开始能够在更长的时间尺度上持续执行任务，甚至在真实工程环境中进行复杂的交互。这种能力的提升，正在改变软件开发的基本范式 —— 从人类开发，或者人机协同开发，转向了 Agent 自己主导的开发范式。Agent 不再只是负责某个一环节的编码，而是开始承担起整个开发流程的责任，交付最终的产物。

那么我们需要优化的重点就不再是 prompt，而是一整套支撑 Agent 工作的工程环境。这被我们称为 Agent Hareness Engineering。更准确一点说，它是在构建一套结构化的约束系统，让 Agent 能够在其中持续运行、持续试错、持续交付，而不会迅速退化。

为什么是现在？

第一，模型能力确实跨过了一个门槛。过去我们谈 Agent，很多时候还是「能演示一个 workflow」或者「能勉强完成几个 step」。但现在最强的一批模型，已经开始具备长程执行、工具调用、自主修复、以及在真实工程环境中持续推进任务的能力。它们不再只是补全器，而是开始逼近真正的执行体。

第二，当 Agent 的代码吞吐量显著超过人类工程师时，问题的性质就变了。人类不再应该把时间主要花在「亲自把代码写出来」，而是应该把时间投入到更高杠杆的位置：定义环境、澄清目标、建立反馈回路、设计约束系统。

但这并不意味着问题自动解决。恰恰相反，如果没有支撑结构，Agent 只会更快地产生架构漂移、更快地堆积技术债、更快地让代码库腐烂。也就是说，模型能力变强，反而让工程系统本身变得更重要。

Harness 不是 Prompt Engineering 的升级版

很多人第一反应会把这件事理解成「更高级的 prompt engineering」。我觉得这并不准确。

Prompt 解决的是一次性表达意图的问题，而 harness 解决的是 让 Agent 在复杂工程里可持续工作 的问题。后者不是一句提示词能补齐的，它涉及三件彼此耦合的事情：

反馈回路：Agent 改完之后，能不能自己复现、验证、审查、修复，而不是写完就停。
执行环境：Agent 能不能获得足够的上下文，能不能操作真实系统，能不能看到运行结果。
约束系统：架构、风格、质量要求，能不能被编码成机械执行的规则，而不是留在人脑里。

如果只给 Agent 一个 repo 和一段需求，它大概率还是会陷入局部最优：修一个点、坏一片；能跑起来，但越来越乱；能过一次，但无法长期维护。Harness engineering 的目标，就是降低这种失控的概率。

一个更简单的定义

如果要用一句尽量直白的话来定义它，我会说：

Agent harness engineering，就是搭建一个结构化的工程系统，让 Agent 可以在里面长时间运行，而不持续退化。

这里最关键的词不是「智能」，而是「结构化」。因为大模型已经足够强，真正稀缺的反而是那套能把能力稳定兑现出来的环境。

第一部分：构建反馈回路

Agent 系统的分水岭，不在于它第一次能不能把代码写对，而在于它能不能自己进入反馈循环。也即，是否能跑通「生成-反馈-改进」的闭环。

每个部分分别包括： 1. 生成：Agent 结合上下文和需求，给出代码编辑方案； 2. 反馈：编译、执行、测试生成的结果，并得到反馈信息； 3. 改进：Agent 根据反馈信息，进行归因，并生成新的编辑方案。

这本质上是一套 generator-evaluator 的闭环。生成只是第一步，关键在于 evaluator 是否真实、是否可执行、是否能持续工作。

这一点在前端美学评估上尤其明显。过去我们做这类问题时，常常失败在两个地方：一是过于抽象，试图直接优化「审美」；二是太早把重点放在奖励模型、RL 或小模型替代上。但更合理的顺序应该是先把模糊主观标准拆成少数几个可评估维度，比如 design quality、originality、craft、functionality，然后用强模型加真实浏览器执行，把 evaluator 跑通。系统先闭环，再考虑局部替换和成本优化。

Auto Research 也是同样的逻辑。它厉害的地方，不一定是 agent 本身多神奇，而是它把研究问题改造成了一个封闭实验循环：只允许修改特定文件，固定训练时长，固定验证指标，看 val_bpb 有没有提升。这个系统之所以有效，是因为它把探索空间、执行权限和评价标准都一起收紧了。

第二部分：执行环境

过去我们会把截图、日志、trace、指标、文档这些东西当成「辅助信息」。但如果主体执行者从人切换成 Agent，它们就不再是辅助品，而是能力的一部分。

举几个非常具体的例子。

如果 Agent 无法直接看到页面效果，那么 UI 修复基本上就是盲修。它可能能改 JSX、CSS、组件逻辑，但它并不知道改完之后视觉层面是否真的变好了。所以需要把截图能力、DOM snapshot、浏览器导航、甚至前端美学评估能力接入到它的运行环境里。

如果 Agent 无法读日志、查指标、看 trace，那么后端和线上问题的处理也会很脆弱。它能改代码，但不知道服务为什么慢、不知道哪里报错、不知道一个修复是否真的改善了关键用户路径。只有当这些观测能力被暴露给 Agent，它才真正拥有「闭环排障」的条件。

再进一步，如果应用本身不能为每个任务独立启动一个临时实例，那 Agent 连安全实验都很难做。一个很值得借鉴的思路是：让每个 git worktree 都能拉起自己独立的一份应用实例，并配套临时的日志、指标和调试环境。这样 Agent 才能在隔离沙箱里复现 bug、验证修复、完成回归检查。

所以环境并不是「让 Agent 更方便」，而是在重新定义 Agent 的可行动边界。看不到，就等于不存在；不能操作，就等于不能做。

第三部分：约束系统

约束是保持项目的可维护性和一致性的关键，我们需要避免项目随着时间的推移而劣化（变成屎山）。因为 Agent 最怕的不是规则多，而是边界模糊。没有明确边界时，它会复用仓库里已有的坏模式，会逐步产生风格漂移，也会不断引入局部看似合理、全局却不可维护的实现。所以一个好的 harness system，必须把约束写进系统里，而不是写在人类共识里。

这些约束通常包括：

架构约束：固定分层、固定依赖方向、限制跨域入口。
编码约束：命名规则、文件大小限制、结构化日志、schema/type 约定。
验证约束：边界解析、结构测试、自定义 lint、CI 检查。
演化约束：对漂移和「AI 残渣」做持续扫描和自动修正。

其中一个很重要的思路：不要靠 prompt 微操 Agent，而要靠硬约束控制 Agent。

比如，明确规定每个业务域只能沿着固定层次依赖；横切能力只能通过有限的 provider 入口进入；所有越界行为都由 linter 和结构化测试自动拦截。再比如，把「taste invariants」也编码进去，让风格、日志、可靠性要求变成机器可执行的规则，而不是 reviewer 的临场发挥。

这类规则在人类协作流程里会显得有点「教条」，但在 Agent 系统里，它们是必要的基础设施。一旦规则编码完成，它就可以被稳定地应用到每一次运行、每一个 PR、每一行新生成的代码上。

文档系统也必须按 Agent 的方式重构

还有一个经常被低估的问题是：Agent 能看到什么？

从 Agent 的角度看，凡是不在运行时上下文里、不在仓库本地、不可检索的知识，都等于不存在。Slack 讨论、口头共识、Google Docs、某个资深工程师脑子里的经验，如果不能被结构化沉淀进仓库，它就无法进入系统推理。

这意味着文档系统本身也要重构。

我非常认同「给 Agent 一张地图，而不是一本一千页说明书」这个原则。AGENTS.md 不应该是百科全书，而应该是目录。真正的知识应该被拆进 docs/、架构说明、执行计划、质量文档、约束规则中，并且通过 lint 和 CI 保证这些文档是新鲜的、互相链接的、可执行的。

文档不再只是给人读的，它同时是 Agent 的推理底座。计划也不再只是沟通材料，而应该是版本化的一等工件。只有这样，Agent 才能逐步获得「从仓库直接理解业务与架构」的能力。

人类角色正在上移

如果说过去工程师的核心产出是代码，那么在这个范式下，人类角色正在整体上移。人类更像是在做几件事：

决定优先级和目标。
把用户反馈翻译成验收标准。
判断系统缺了什么能力。
把这些缺失转化为新工具、新规则、新文档和新环境。

也就是说，人类的价值不再主要体现在「亲手写出某个函数」，而体现在「为 Agent 建立一个可以反复获胜的系统」。

当 Agent 卡住时，最应该追问的问题也不再是「能不能把 prompt 再润色一下」，而是：

它是不是缺上下文？
它是不是缺反馈信号？
它是不是缺约束边界？
它是不是缺一个能自动化执行的评估器？

如果这几个问题没有被解决，模型再强，也只是在更快地撞墙。

我现在的理解

到这里，我对 Agent Hareness Engineering 的理解可以收束成一句话：

研究如何构建一套系统化的 Agent 脚手架，使得 Agent 在其中能够稳定地产生正确、可维护、可演化的软件，并直接得到可交付的产物。