Harness Engineering，构建智能体工作系统的行为准则

本文是以OpenAI的Harness工程报告作为研究案例，考虑《Harness Engineering学习二 —— OpenAI的实践》中已经专门记录了相关内容，因此，本章节后续重复部分，将不在记录。

1 系统概述

1.1 几点总结

1. Harness工程为编码智能体进行环境设计：约束、文档、反馈环、生命周期工具；
2. 智能体的正确性取决于它能检索和观察到的信息，提示上下文、repo文档、工具输出、运行信号；
3. 架构意图必须机械强制执行（静态分析/CI），不能只是记录在案，因为智能体工作必须大规模可复制；
4. 使得运行系统清晰易读（日志/指标/跟踪 + 用户界面自动化），以便能够自动化验证，而非人工目视检查；
5. 针对新的稀缺资源“人类注意力”进行优化。相较于缓慢的人工确认，更倾向于快速检测 + 低成本回退。

1.2 最小可行Harness检查单

1. 一个指向更深入文档的小型AGENTS.md入口点，更深入文档的内涵包括：命令优先、版本化、大刀阔斧地精简；
2. 可复现的开发环境（一键启动），每个工作树的隔离，以防止跨任务污染；
3. CI中的固定规则：架构边界、格式化、边缘数据验证、依赖规则；
4. 智能体可读性hook：结构化日志 + 可查询的trace/指标，重复的用户界面/测试驱动 ；
5. 智能体可运行和解释的清晰的评估阀：“完成”标准、回归测试、安全检查；
6. 安全防护：最小权限凭证、受控出口、审计日志、回滚操作手册。

1.3 Harness术语及其为何重要

从智能体优先的软件开发角度出发，Harness是为AI模型指引方向所构建的一切，因为AI模型虽然快速且能力强大，但它并不知道该去何方。

Harness工程是一个让编码智能体能够规模化可靠操作的新兴学科，设计工作包括：约束、反馈环、文档结构、静态分析规则、观察管线、生命周期管理系统。更准确来说，它属于元工程范畴：即设计工程发生的环境。

如果说2025证明智能体可以写代码，则2026年产业界认识到：智能体不是最难的那部分，但Harness是。

2 工程含义的转变

2.1 从码农到系统设计师

智能体优先的工作流中，最大的变化不是技术，是认知：工程师的工作从生产正确的代码转向为智能体生产正确的代码构建正确的环境，两者有着根本性的不同。

传统软件工程的工作情境是：当软件崩了，人工开始调试。查看过程状态，添加日志，分析失败原因。修复就是修改代码。

Harness工程的工作情境是：当软件崩了，几乎不可能去问“智能体写的代码哪出错了？”修复工作也不可能是“更加努力干”。因为只有一种方法，就是让Codex去干，人类工程师总师深入任务并提问“缺什么能力？我们如何确保它对智能体来说，既清晰易读又具有可执行性？”

这种重构改变了下游的所有东西。人类工程师在智能体优先环境中是一个系统设计师，一个环境建造师，一个反馈架构师。

Harness工程将人类工程师的工作重点由开发代码变成设计环境、指定意图、提供结构化反馈。Codex直接与开发工具交互，打开PR，评估变更，不断迭代，直到满足任务标注。

2.2  稀缺性翻转

传统软件开发，计算资源便宜，人类注意力相对稀缺。开发人员通常受限于复杂性，而非吞吐量。

智能体优先环境中，这个关系发生了翻转。随着代码吞吐量的增加，瓶颈变成了人工质量保证（QA）能力。由于固定约束是人类的时间和注意力，我们致力于通过使应用界面、日志和应用指标本身对Codex直接可读，来为智能体增加更多功能。

稀缺资源变成了人的时间和注意力，而非计算能力。这会改变所有工程的权衡设计。等待成本高昂，纠错成本低廉。

3 Harness工程的核心技术原语

3.1 仓储知识作为真实知识

以智能体为中心的工程中，最违反直觉的教训之一与信息架构有关。智能体只能推理它们在工作集中能看到的内容：提示上下文、检索到的文档、工具输出、运行观察。存在于聊天消息、谷歌文档、人们头脑中的知识在操作上是不可见的，除非特意将其接入工作范围。

这产生一个实践需求：任何你希望影响智能体行为的知识，都必须使其机器可访问。最稳妥的选择是在仓库中实现它（版本化、可审查、可测试），或者提供一个明确的检索系统，该系统本身由仓库定义和强制执行。

OpenAI团队将他们的知识库结构化为一个分层的文档目录：

AGENTS.md               ← table of contents (~100 lines)
ARCHITECTURE.md         ← top-level domain map
docs/
├── design-docs/        ← indexed, verified architectural decisions
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/
│   └── db-schema.md
├── product-specs/
├── references/         ← external library docs reformatted for LLMs
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

该结构中所蕴含的关键洞察在于目录与百科全书之间的区别。一个试图捕获所有内容的单一AGENTS.md会因为可预见的原因而失败，团队对此进行了明确记录：

• 上下文拥挤：一个庞大的指令文件会取代任务、代码、相关文档在上下文中的位置，使智能体在错误的约束条件下进行优化。
• 过度指导等于没有指导：当每件事都标记为重要时，智能体会在本地进行模式匹配，而不是有意识地导航。
• 即时腐烂：一本庞大的手册无法进行机械验证。变成了智能体无法验证的陈旧规则的坟墓。
• 隐匿性偏差：没有结构验证，包括覆盖范围检查、新鲜度检查、交叉链接验证，任何单一文档都会静静地衰减。

解决方案是渐进式披露：AGENTS.md是一份带有指引的地图，而非一本手册。智能体从一个小的、稳定的入口点开始，并被告知下一步去哪里。

3.2 AGENTS.md标准

AGENTS.md是一种简单、开放的格式，用于指导编码智能体。一个专门和可预测地提供上下文及指令的地方，帮助AI编码智能体完成项目。AGENTS.md 的出现源于AI软件开发生态圈中的多方协作，包括 OpenAI Codex、Amp、谷歌的 Jules、Cursor 以及 Factory。

大多数编码智能体都将AGENTS.md（或等效文件，如CLAUDE.md）视为高优先级上下文产品，并在工作流中尽早加载。具体行为因工具而异，但你应该将其视为规划和执行中的“关键路径”的一部分。AGENTS.md 是纯 Markdown （md）格式；标题提供语义提示。推荐章节划分：构建与测试（编译和测试的准确命令）、架构概览（主要模块的简述）、安全（身份验证流程、API密钥、敏感数据）、Git工作流（分支、提交约定、PR要求）、约定与模式（命名规范、文件夹布局、代码风格）。

新出现的AGENTS.md约定中，可以分层引导：根文件建立全局默认设置，子目录文件可以使用本地规则对全局默认进行覆盖。在Lopopolo的Harness工程报告中描述的OpenAI仓库中，这一方法被用到了极致：88个AGENTS.md文件，每个主要子系统一个，以保持指令的本地化和最小化。

社区提出一个关键原则：如果你的工具每次运行时，都会自动注入AGENTS.md（许多工具确实如此），那么其中的每个标记都会直接与任务本身竞争。这样就产生了一个预算难题。缓存陈旧是一种现实危害：如果你的AGENTS.md文件指出“认证逻辑位于src/auth/handlers.ts”，而该文件被重命名或移动，智能体就会自信地在错误的地方查找。该文件应描述能力和意图，而非文件系统结构。

GitHub对2500多个代码库的分析发现了一个一致的模式：成功的智能体不仅仅是模糊的助手，更是专家。表现最佳的AGENTS.md文件会尽早给出命令，使用代码示例而非解释，设定清晰的边界，精确指定技术栈，并涵盖六个核心领域：命令、测试、工程结构、代码风格、git工作流程、边界。

3.3 架构约束作为机械不变量

仅凭文档并不能保持完全智能体生成的代码库的连贯性。原因很微妙：智能体在模式复制方面非常高效。它们能学习和重复代码库中存在的任何模式，包括坏模式。如果代码库存在架构漂移问题，智能体会忠实地复制并放大这种漂移。

解决方案是将架构规则从文档中移至机械执行层面。OpenAI团队构建了一个严格的分层领域架构：

Within each business domain (e.g., App Settings):

Types → Config → Repo → Service → Runtime → UI

Cross-cutting concerns (auth, connectors, telemetry, feature flags)

enter only through Providers. Everything else is disallowed.

依赖方向在持续集成（CI）层强制执行，智能体只能通过此序列“向前”引用层。这些静态检查器本身是由Codex编写的。

这种架构，通常要等到一个组织拥有数百名工程师时才会考虑的架构。在智能体优先的工程中成为了早期先决条件。正如Lopopolo所言，正是这些约束条件使得速度得以提升，同时架构不会衰减。在以人为先的工作流程中，这些规则可能会让人觉得过于陈旧或具有限制性。在使用智能体的情况下，它们则成为了倍增器：一旦开始编码，就会立即应用于所有地方。

团队机械执行的其他不变规则：结构化日志、摘要和类型的命名约定、文件大小限制、特定平台的可靠性要求，以及所有外部边界的数据验证。

3.4 智能体应用可读性

随着吞吐量的提升，OpenAI团队发现了他们的第二个主要瓶颈：智能体无法看到正在运行的应用。只有在人工审查后才能发现bug，这导致了对人工QA（质量保证）的速率限制依赖，从而抵消了吞吐量的优势。

解决方案是：让应用本身直接对智能体清晰可见。

• 按工作树启动：该应用可通过每个Git工作树启动，允许Codex为每次变更启动并驱动一个独立的应用实例，以消除并发智能体运行之间的环境污染。
• Chrome DevTools协议集成：该团队将Chrome DevTools协议直接连接到智能体运行时中，并开发出DOM快照、屏幕截图捕捉，以及浏览器导航等功能。使得Codex能够通过直接驱动UI来复现错误，通过观察修复后的应用状态来验证修复效果，并从运行事件中推断UI的行为，而不仅仅是静态代码分析。智能体的反馈环变成：

选择目标 -> 状态前快照 -> 触发UI路径 -> 观察运行事件 -> 应用修复 -> 重启 -> 再次快照 -> 循环直到干净

• 瞬态本地监控栈：每个工作树都有自己独立的可观察性管线，日志、指标和Traces，任务完成后的销毁。该栈使用Vector作为扇出路由，为Victoria Logs（可通过LogQL查询）、Victoria Metrics（可通过PromQL查询）以及分布式追踪提供基础设施。
• 这解锁了一类原本不可能实现的提示：“确保服务启动在800毫秒内完成”或“四个关键用户流程中的任何时间跨度都不超过2秒”。这些变得容易处理，因为智能体可以直接测量结果，而不仅仅是检查代码。该团队经常看到单个Codex在执行单一任务时长达六个小时，而且往往是在人们睡觉的时候

3.5 自动开发环

当搭建足够的脚手架后，该智能体能够在任何中间步骤无需人工干预的情况下，进行端到端功能开发。OpenAI团队描述了他们的自动循环过程：给定一个提示，智能体验证当前代码库状态，重现报告的错误，录制一段视频演示故障，实施修复，通过运行应用来验证修复，录制第二段视频演示修复后的状态，提交PR，响应智能体和人类的反馈，检测并修复构建失败，仅在需要判断时才上报给人类，并合并更改。

由于上述Chrome DevTools和可观察性集成的存在，涉及bug重现、视频捕获和UI验证的步骤才得以实现。整个循环依赖于harness的每一层都准备就绪。

4 风险和安全

智能体吞吐量改变了代码库的风险状况。使智能体高效产出的同一工具也赋予了它杠杆作用：访问存储库、构建系统、凭证和部署路径。这种杠杆作用需要明确的控制。

实践中的具体失效模式：

• 秘密和敏感数据泄露：如果智能体能够读高优先级凭证，它就会将这些凭证泄露到日志中、提交这些凭证、将它们粘贴到问题中，或者通过工具将其窃取。
• 通过工具进行权限提升：广泛的shell访问权限加上宽松的持续集成/持续部署（CI/CD）或云角色，使得“编写代码”变成“更改基础设施”
• 通过仓库内容进行提示注入：如果智能体对其视为策略的内容不够严格，那么文档、问题文本甚至代码中的注释都可能成为对抗性指令。
• 供应链漂移；智能体可以通过增加依赖项、放宽版本限制、引入扩大攻击面的脚本来“修复”问题。

Harness应该采取的默认安全行为：

• 权限最小化设计：使用短生命期tokens、收窄证书范围、读写权限分离（尤其生产系统）。
• 受控出口和工具白名单：将网络访问作为一项明确的能力。默认拒绝，然后严格授权（域、协议、时间窗口）。
• 指令完整性：在熟知的文件（如AGENTS.md）中保持高信任度策略，并对出现在低信任度文件（问题正文、随机文档）中的“策略”进行机械式静态检查。
• 来源与审计追踪：Log工具调用、diff、测试结果和部署操作，以便对事件进行调试，并免责。
• 快速回滚：如果你秉持“修正成本低”的合并理念，那么你必须在快速检测和回滚上投入精力；否则，就是在拿生产冒险。

5 度量和成果

Harness并非基于感应。如果你希望智能体吞吐量既高效又无混乱，就需要一些指标，这些指标能够在机器运转时清晰显示质量和安全性。

有用的测量趋向集中在几个区间内：

• 吞吐量：首次PR（Pull Request，拉取请求）时间、合并时间、每日完成的任务数、每个任务的平均迭代次数。
• 质量：合并时的CI通过率、缺陷漏出率、回退频率、检测回归的平均时间。
• 人工注意力：每个PR的审核时长、升级次数、需要人工判断的任务占比。
• Harness健康：文档新鲜度违规、架构边界违规、测试失败率、工具/运行时错误率
• 安全：被阻止的出口尝试、权限拒绝、秘密扫描命中、需要批准的依赖关系变更。

核心教训：让智能体（通过工具和仪表板）获取这些指标，而不仅仅是人类。当智能体能够看到什么是“好”的时候，其性能提升最快。

6 规模化知识管理

6.1 计划作为一流仓库产物

传统软件工程将大部分计划状态保存在仓库之外，在项目管理工具、Jira工单、Confluence页面和Slack会话中。智能体优先的开发中，这是一个根本性的架构缺陷：上下文中不可见的任何知识，智能体都无法访问它。

OpenAI团队将执行计划作为版本化的仓库产物。轻量级的临时计划涵盖小的变更；复杂工作则以包含进度和决策日志的结构化执行计划来记录。活动计划、已完成计划、技术债务Trace都进行了版本控制，并与源代码位于同一位置。

这有一个重要的含义：处理后续任务的智能体可以推理出在先前任务中做出的决策、这些决策背后的根本原因，以及已知技术债务的当前状态，而无需任何人为其提供上下文。

6.2 文档检查与时效性强制

团队机械地强制执行文档质量检查：专门的检查工具验证知识库是否相互关联且结构正确；CI检查与代码相关的文档的新鲜度；一个循环“文档整理”智能体扫描那些无法反映实际代码行为的过时文档，并自动发起修复PR请求。

人类的偏好一旦被捕捉到，就会持续得到强化。这类似于知识的垃圾清理，需要的是小规模、持续的维护，而不是偶尔痛苦的大扫除。

6.3 熵问题：AI残留与黄金法则

完全智能体自主引入了一个模式复制问题。智能体从现有代码中学习，并忠实地复制其模式，包括那些次优（非最佳）的模式。随着时间的推移，这会导致偏差和不一致，团队称之为“AI 残留”：由于这些模式存在于代码库的有效训练分布中，因此它们会激增。

起初，人们通过手动方式解决该问题。团队过去常常用周五时间去清理AI残留，占一周时间的20%，但这种方式无法扩展。

他们的解决方案是“黄金原则”：将固执的、机械化的规则直接编码到仓库中。以OpenAI的实现为例：优先使用共享工具包，而非手工编写的辅助工具（保持不变量的集中化）；在边界处验证数据，而非推测性地探测形状；使用团队配备OpenTelemetry并发工具，而非行为不透明的第三方并发原语。

一系列后台Codex任务会定期运行，包括扫描偏差、更新质量等级、发起有针对性的重构PR。大多数任务可以在一分钟内完成审查并自动合并。

7 更广泛的生态

7.1 智能体对比

关于“哪种智能体最好”的大多数争论都忽略了Harness：执行环境决定了你的限制。终端驻留智能体继承了你的本机。云智能体继承了你配置的沙箱。同一个模型的表现可能会因它看到和接触到的东西而大相径庭。

以下是从Harness相关术语角度进行的实际对比

工具类别	执行层面	上下文文件约定	沙盒与权限	反馈环	Harness必须物
OpenAI Codex	云任务+本地（CLI/IDE）	AGENTS.md	独立的任务环境；权限和互联网访问权限明确授权	基于PR的迭代+测试+工具输出	可复现的环境、机械式CI阀，智能体可视的运行时信号
Claude Code	本地终端	CLAUDE.md	继承本地权限，除非添加新限制	本机上严格的编译/测试环	强大的本地开发工程学、保密卫生，工具使用防护

Codex用GPT-5.3-Codex模型系列写代码。

7.2 两条路径

实践中，智能体驱动开发往往围绕两种互补的模式进行：

• 多智能体执行：协调性和并发性是首要产品特征。
• 意图优先架构：规范和约束对智能体行为的塑造要大于临时提示。

两条路径并非互斥。Harness工程是使两者都能发挥作用的关键，是将智能体能力转化为可靠生产吞吐量的基础设施层。

8 未解之谜

Harness工程作为一种正式的实践仍然处于起步阶段。仍存在几个悬而未决的实证问题：

• 长期视角下的架构连贯性：目前尚无人知晓一个完全由智能体生成的代码库多年来是如何在架构上进行演变的。黄金法则方法解决了局部漂移问题，但在连续智能体操作下，大规模架构的一致性降低、改进或保持稳定，这一问题尚未解决。
• 模型能力曲线：当前的Harness设计弥补了模型的局限性。随着模型的改进，一些Harness组件将变得多余。Harness需要设计为可剥离的，为规避模型限制而引入的复杂性，在模型不再需要时，应能识别并移除。Harness的设计随模型动态变化。
• 人类判断最集中的地方：我们仍在探索人类判断力在何处能发挥最大作用，以及如何将这种判断力编码以使其产生复合效应。
• 普适性：上述自主开发循环在很大程度上取决于特定仓库的具体结构和工具。不应认为无需同等投入即可普遍推广，至少目前还不行。

9 工程团队的实践意义

对于考虑智能体优先方法的团队而言，OpenAI实验的经验教训表明了一个明确的投入层次：

• 首先投资文档基础设施：不是提词工程。智能体输出的质量受其操作的上下文质量的限制。一个结构良好的知识仓库比提示调优能产生更好的结果。
• 机械地编码结构规则：如果一个架构约束重要到需要记录在案，那么它也重要到需要用静态检查工具来强制执行。没有得到机械地强制执行的文档将会产生漂移。
• 应用对智能体清晰可读：任何需要人工检查正在运行的应用的验证都是瓶颈。应投资开发工具，让智能体能够直接观察、测量和推理运行时行为。
• 将技术债视为连续自动化的过程：智能体生成代码的熵问题是真实的，但可通过自动清理周期来管理。定期的人工清理突击行动不能规模化使用。
• 根据实际成本结构调整合并理念：如果智能体的吞吐量超过人类审查能力，等待是昂贵的，修改是便宜的。源于不同成本结构的工程规范将系统性地产生反效果。
• 构建随模型一同进化的Harness：不要为当前模型的局限性过度设计应对方案。在结构化要素上投入：文档、架构不变量、反馈循环，这些随模型能力的提升仍将保持其价值。

10 核心洞察

很清楚的是：构建软件仍然需要行为规范，但这种行为规范更多地体现在脚手架上，而非代码编写上。保持代码库一致性的工具、抽象概念和反馈循环是越来越重要。

Harness工程的核心洞察看似简单：在智能体优先的软件开发中，瓶颈通常不在于智能体编写代码的能力，而是智能体运行的环境质量。

智能体不是工程判断的替代品，而是工程判断的倍增器，以机器速度运行。判断仍然需要来自某个地方。Harness工程就是确定这个“地方”在哪里，对其进行精确编码，并使其对一个只能看到仓库内容的系统来说清晰可读。