Harness Engineering 调研

日期：2026-03-13
主题：OpenAI Harness Engineering、Cursor Towards self-driving codebases / Scaling long-running autonomous coding
结论先行：harness engineering 不是单指提示词工程，也不是单个模型能力，而是围绕代理开发构建的一整套运行环境、知识系统、约束机制、评测反馈、观测与收敛流程。它解决的是“怎样让 agent 在真实代码库里持续、稳定、可审计地产出可合并的软件变更”。

核心结论

Harness engineering 的本质，是把软件工程的重心从“人直接写代码”转向“人设计环境、指定意图、建立反馈回路，agent 负责执行”。OpenAI 在官方文章中直接写到："Humans steer. Agents execute."，并称他们在 5 个月里构建并交付了一个内部 beta，且是 "0 lines of manually-written code"。OpenAI
这套方法的关键不在于单次 prompt，而在于让 agent 拥有可工作的环境：可启动的应用、可访问的日志/指标/trace、可执行的 CI、可引用的仓库知识、可验证的架构边界、可复用的评测流程。OpenAI
Cursor 的“self-driving codebases”与 OpenAI 的 harness engineering 在工程哲学上高度同构：二者都强调多 agent 编排、角色分层、强可观测性、结构化 handoff、允许局部错误但追求整体收敛，而不是追求每一步绝对正确。Cursor self-driving codebases Cursor scaling agents
OpenAI 后续关于长程任务的官方文章进一步说明：真正起作用的不是超长单 prompt，而是 plan -> implement -> validate -> repair -> repeat 的 agent loop，以及 prompt/spec、plans.md、implement.md、documentation.md 这类“持久项目记忆”。Run long horizon tasks with Codex
因此，harness engineering 可以理解为“agent-first 软件工程基础设施与操作系统”。它覆盖知识管理、执行编排、测试评估、审查合并、质量回收，以及长期自治运行的防漂移机制。

什么是 Harness Engineering

1. 定义

OpenAI 的定义不是一句术语解释，而是一套实践描述：当团队的主要工作“不再是亲手写代码，而是设计环境、指定意图、建立反馈循环，让 Codex agents 稳定工作”时，工程工作的核心就转向 harness。OpenAI

可压缩成一句中文：

Harness engineering = 为 agent 构建能可靠工作的工程环境、知识底座、控制规则和反馈回路。

OpenAI 原文中的几个关键句：

"Humans steer. Agents execute."

"The primary job of our engineering team became enabling the agents to do useful work."

"Our most difficult challenges now center on designing environments, feedback loops, and control systems"

来源：OpenAI

2. 它不是什么

不是单纯的 prompt engineering；prompt 只是入口，不是系统本体。
不是把大模型接进 IDE 就算完成；真正难的是让 agent 能持续完成端到端任务。
不是“自动写代码”这么窄；OpenAI 明确说 agent 生成的是“application logic, tests, CI configuration, documentation, observability, and internal tooling”。OpenAI

3. 为什么现在重要

单 agent 在复杂项目上会失焦、早停、过度自信；Cursor 明说单 agent 适合聚焦任务，但面对复杂项目“slow for complex projects”。Cursor scaling agents
随着 agent 运行时间变长、任务链变深，真正的瓶颈从“模型会不会写”转向“系统会不会稳定地让它持续做对的事”。
所以竞争壁垒开始从模型参数，转向环境设计、文档结构、边界约束、评测体系和恢复机制。

Harness Engineering 的组成部分

1. 仓库知识要成为 system of record

OpenAI 的一个核心观点是：agent 能看到的才存在，不能在运行上下文中访问的知识，对 agent 等于不存在。

"From the agent’s point of view, anything it can’t access in-context while running effectively doesn’t exist."

"We made repository knowledge the system of record"

他们反对一个臃肿的单文件 AGENTS.md，转而把 AGENTS.md 当目录，把真正的知识放进结构化 docs/、架构文档、执行计划、技术债跟踪与质量文档中，并用 linter / CI 机械检查其新鲜度与交叉链接。OpenAI

含义：

harness 的第一层不是模型，而是“仓库内可检索、可验证的知识组织”。
文档不是给人看的附属品，而是 agent 的运行时依赖。

2. 让应用、日志、指标、trace 对 agent 可见

OpenAI 把 UI、日志、指标、trace 都做成 agent 可调用的运行时能力：

"Logs, metrics, and traces are exposed to Codex via a local observability stack"

"Agents can query logs with LogQL and metrics with PromQL."

并给出类似 "ensure service startup completes in under 800ms" 这样的可验证目标。OpenAI

这意味着 harness 不只是代码生成器，而是“agent 可观测的测试与诊断平台”。

3. 架构与 taste 要靠机械约束，不靠口头约定

OpenAI 明确强调：

"By enforcing invariants, not micromanaging implementations, we let agents ship fast without undermining the foundation."

它们使用分层架构、定制 linter、结构测试、命名规范、日志规范、文件大小约束等方式，为 agent 提供硬边界。OpenAI

这和传统“给人写代码规范”不同：

对 agent，模糊规范几乎等于没有规范；
规则越能转为程序检查，越容易规模化复用；
taste 需要被编码成 lint / test / docs，而不是停留在 code review 口头意见里。

4. Throughput 会改变 merge 哲学

OpenAI 公开指出，在 agent 吞吐远高于人类注意力时，过重的阻塞式合并门槛会变成系统性瓶颈：

"Test flakes are often addressed with follow-up runs rather than blocking progress indefinitely."

"In a system where agent throughput far exceeds human attention, corrections are cheap, and waiting is expensive."

来源：OpenAI

这并不意味着放弃质量，而是把质量控制从“每一步人工卡死”转向“快速前进 + 后续自动修正 + 周期性清理”。

5. 需要持续做 entropy control / garbage collection

OpenAI 很坦率地承认全 agent 代码库会累积“AI slop”，他们早期甚至每周五花 20% 时间做清理，后来才把“golden principles”编码进仓库并由后台任务持续发起小型清理 PR。OpenAI

这说明 harness 不是“一次搭好”的系统，而是持续维护的软件工厂：

需要周期性质量评分；
需要 refactoring PR 自动生成；
需要技术债像垃圾回收一样被持续处理。

6. 长程任务依赖 durable project memory，而不是超长单 prompt

OpenAI 在 Run long horizon tasks with Codex 中把 long-horizon coding 拆成了非常明确的 agent loop：

"Plan" -> "Edit code" -> "Run tools" -> "Observe results" -> "Repair failures" -> "Update docs/status" -> "Repeat"

并明确指出：

"Long-running work is less about one giant prompt and more about the agent loop the model operates inside."

"The most important technique was durable project memory."

来源：Run long horizon tasks with Codex

它给出的文件栈也很值得注意：

prompt.md：冻结目标与约束；
plans.md：里程碑与 acceptance criteria；
implement.md：运行手册；
documentation.md：状态与决策日志。

这与 OpenAI 主文里“repository knowledge is the system of record”形成直接互证：

harness 的核心是外部化状态；
任务越长，越依赖可回看的结构化记忆；
让 agent 长时间不漂移的关键，不是无限加上下文，而是把上下文整理成可重访的项目内工件。

7. ExecPlan / AGENTS / PLANS 说明 harness 不只是理念，而是可落地模板

OpenAI Cookbook 的 Modernizing your Codebase with Codex 把这种做法进一步模板化。它建议在仓库中建立 .agent/AGENTS.md 和 .agent/PLANS.md，并把复杂改造工作收敛到 ExecPlan 驱动的多阶段流程中。Modernizing your Codebase with Codex

关键表述：

"Give Codex a lightweight contract for how planning works in this repo"

"These explain what an ExecPlan is, when to create or update one, where it lives, and what sections every plan must have."

这意味着 harness engineering 在实践上至少包含三类 repo 内契约：

agent 如何理解仓库的契约：AGENTS.md
agent 如何规划复杂任务的契约：PLANS.md / ExecPlan
agent 如何验证自己完成了任务的契约：validation docs / tests / parity checks

换句话说，harness engineering 并不是一句抽象口号，而是能沉淀成文件结构、计划模板和执行脚手架的工程方法。

Cursor 文章给出的互证

1. Cursor 证实了“结构比聪明更重要”

在 Towards self-driving codebases 中，Cursor 说他们“created a new agent harness to orchestrate many thousands of agents”，而且系统可以运行一周、完成大部分提交。Cursor self-driving codebases

这和 OpenAI 的观点高度一致：突破点不是单个 agent 更聪明，而是 harness 让大量 agent 可被编排、被观察、被收敛。

2. 平铺式自协调很快失败

Cursor 的早期方案是多 agent 共享协调文件，但很快出现锁竞争、忘记释放锁、状态混乱等问题：

"20 agents would slow to the throughput of 1-3"

"The coordination file quickly created more problems."

来源：Cursor self-driving codebases；Cursor scaling agents

它说明 harness engineering 不能只理解为“多开几个 agent 并行跑”，而是必须解决同步、 ownership、任务切分和信息回流问题。

3. 最终有效的是 planner / subplanner / worker 的层次系统

Cursor 最终收敛到 root planner、subplanner、worker 的递归结构，worker 只做单一任务，planner 负责全局拥有权与后续决策；handoff 不仅传结果，还传 "notes, concerns, deviations, findings, thoughts, and feedback"。Cursor self-driving codebases

这与 OpenAI 的“人负责高层意图、agent 负责执行”形成互证：

大任务必须拆为多层 ownership；
handoff 必须结构化，才能支撑长期自治；
高吞吐系统不能依赖人人都知道全局，而是依赖清晰的局部责任与信息上卷。

4. 正确率与吞吐量之间需要工程取舍

Cursor 明确写到：

"When we required 100% correctness before every single commit, it caused major serialization and slowdowns of effective throughput."

他们更倾向接受一个“小而稳定的错误率”，再靠最终收口到 green branch 的修复阶段控制发布质量。Cursor self-driving codebases

这个观点与 OpenAI “merge gate 变轻、修正更便宜”高度一致，是目前公开材料中最值得关注的共识之一。

Harness Engineering 与评测 / Evals 的关系

如果说 harness 是 agent 的“运行系统”，那 evals 就是这个系统的“仪表盘和回归测试框架”。

OpenAI 官方 Agent evals 文档写得很直接：

"Measure agent quality with reproducible evaluations."

"For identifying errors at the workflow-level, we recommend our trace grading functionality."

来源：Agent evals

OpenAI 官方 Trace grading 文档进一步定义：

"Trace grading is the process of assigning structured scores or labels to an agent’s trace"

"Unlike black-box evaluations, trace evals provide more data to better understand why an agent succeeds or fails."

来源：Trace grading

这说明 harness engineering 不是“先让 agent 跑起来，再想办法测”，而是要把以下能力内建进去：

端到端 trace 留存；
对工具调用、决策路径、失败点的结构化打分；
可以大规模回归的 eval 运行；
把“为什么失败”而不是只看“结果对不对”纳入系统反馈。

换句话说：

没有 eval / trace grading 的 harness，很难稳定演化；
没有 harness 的 evals，也很难真正改善 agent 在真实工程流里的表现。

2. skill / workflow 的 eval 更接近“轻量端到端测试”

OpenAI 在 Testing Agent Skills Systematically with Evals 里把 agent skill 的评测说得非常工程化：

"Concretely, an eval is: a prompt -> a captured run (trace + artifacts) -> a small set of checks -> a score you can compare over time."

"In practice, evals for agent skills look a lot like lightweight end-to-end tests"

来源：Testing Agent Skills Systematically with Evals

这对 harness engineering 很关键，因为它说明：

harness 的评测对象不是只看最终回答文本；
还要看 agent 有没有调用正确 skill、执行预期命令、生成约定输出；
trace、artifacts、command execution 本身就是评测材料。

这比传统 LLM eval 更贴近真实软件工程，也更接近 survey session 里应强调的“系统性方法论”。

3. eval 不是孤立模块，而是持续改进 flywheel 的一环

OpenAI 官方 Agent evals 还明确把它和持续改进绑在一起：

"Operate a flywheel of continuous improvement using evaluations."

而在 Safety in building agents 中，又把 trace graders 和 evals 作为多 agent workflow 的安全与质量缓解手段之一。Safety in building agents

这进一步支持一个判断：

harness engineering = 运行时脚手架 + 观测 + 评测 + 安全约束 + 持续修正的闭环。

Harness Engineering 与 AI-native engineering team 的关系

OpenAI 官方 Building an AI-Native Engineering Team 给了一个更组织化的视角：coding agents 正在把工程团队从“自己做所有实现”转向“把大量 SDLC 阶段交给 agent 首轮执行，人类负责 review / own / direction”。Building an AI-Native Engineering Team

其中几条很值得和 harness engineering 放在一起看：

"Persistent project memory"
"Evaluation loops"
"Structured tool execution"

这实际上说明，组织层面的 AI-native engineering，底层正是 harness engineering：

如果没有持久项目记忆，agent 无法稳定参与长流程；
如果没有结构化工具执行，agent 产出不可验证；
如果没有 evaluation loops，团队无法知道 agent 是在变好还是只是在漂移。

Harness Engineering 与 Benchmark 的关系

1. Benchmark 是外部度量，harness 是内部生产系统

SWE-bench 的定位是公开基准，衡量 agent 在真实软件工程问题上的解决率；官网强调 "% Resolved" 作为核心指标，并列出 Verified、Lite、Multilingual、Multimodal 等变体。SWE-bench

因此：

benchmark 用来回答“你的 agent 在标准题上表现如何”；
harness 用来回答“你的团队能否在真实仓库里持续做出可交付变更”。

两者相关，但不能互相替代。

2. 公开基准很重要，但不足以覆盖真实 agent 工程问题

OpenAI / Cursor 的文章都更强调真实仓库中的长期运行问题：

文档是否可检索；
日志/trace 是否可访问；
agent 是否会漂移；
多 agent 是否会互相踩踏；
架构边界是否能被机械执行；
merge / review / cleanup 能否闭环。

这些问题不是单一 benchmark 分数能完整描述的，所以 harness engineering 可以看作 benchmark 之外的“生产工程层”。

3. EVMbench 提醒我们：benchmark 也会反过来推动 harness 设计

Paradigm 与 OpenAI 联合发布 EVMbench 时，用词很直接：

"Together with OpenAI, we built EVMbench to measure exactly that."

"EVMbench is an open evaluation framework that tests AI agents across detecting, patching, and exploiting vulnerabilities."

"We’ve also extended the benchmark harness into an auditing agent"

来源：Paradigm - Introducing EVMbench

这里有一个非常重要的信号：

benchmark 不只是外部排行榜；
benchmark 的容器化环境、answer key、任务封装，本身就在塑造 harness；
当 benchmark 足够贴近真实工作流时，它会自然长成一个可复用的 agent harness。

它和我们当前 blog / 功力系统 / survey sessions 的相关之处

当前工作区里没有现成的 survey sessions 或已有 harness engineering 调研文件，因此本次是新建调研。结合你的描述，harness engineering 和你们现有内容体系最相关的地方至少有四个：

1. 对 blog 来说，它是一个上位框架

如果你们 blog 已经在写 agent、评测、工作流、技能系统、代码生成、自动化开发，那么 harness engineering 可以作为一个总纲，把这些零散主题串起来：

不是只谈 agent 能力；
而是谈“怎样设计一个 agent-first 的工程系统”。

2. 对“功力系统”来说，它非常像工程内功

如果“功力系统”强调的是长期积累、基本功、抽象能力、方法论沉淀，那么 harness engineering 正是 agent 时代的软件工程内功：

文档治理能力；
约束编码能力；
评测建设能力；
工作流设计能力；
可观测性与质量回收能力。

它不像 flashy demo，更像“把 agent 变成稳定生产力”的底层功法。

3. 对 survey sessions 来说，它很适合做系列主题

这个话题不该只做成一篇新闻摘要，后续完全可以拆成系列：

Harness Engineering 是什么
Agent legibility 与 repository as system of record
Trace grading 与 agent eval flywheel
Multi-agent orchestration 的设计模式
Throughput vs correctness 的工程权衡
Agent-first codebase 的 garbage collection

4. 对实际系统设计来说，它可直接映射到你们自己的 agent 产品/内容体系

如果你们已经有 blog 系统、技能系统、survey session 机制，那么可以把 harness engineering 直接翻译为内部建设议题：

知识是否沉淀在 repo / docs，而不是散落在聊天和口头沟通；
规则是否能被 lint / CI / grader 机械执行；
agent 每次执行是否留下 trace、可复盘结果与失败原因；
是否有定期 cleanup / refactor / debt paydown 的后台流程；
是否建立了从任务定义到 PR 合并的闭环。
是否已经形成 spec -> plan -> implement -> verify -> document -> review -> merge 的标准回路。

对我们自己的可执行启发

1. 先做知识底座，再做更强 agent

比起继续堆 prompt，优先做这些事情更符合 harness engineering：

给仓库建立清晰的 AGENTS.md 目录索引；
把产品规则、架构规则、执行计划、质量标准写进 repo；
用 CI 检查文档 freshness 和 cross-link completeness。
给长任务建立持久项目记忆文件，而不是只依赖会话上下文。

2. 先做可观测性，再做自治

如果 agent 不能看日志、trace、指标、UI 状态，它就只能“猜”。Harness engineering 的核心恰恰是减少猜测，让 agent 能自己验证。

3. 先做约束编码，再做规模化并发

没有边界时，多 agent 容易把错误放大；有边界时，多 agent 才能带来真实吞吐提升。

4. 先做 eval flywheel，再谈可靠交付

OpenAI 近几篇文档连起来后，比较清楚的一条路线是：

用 AGENTS.md / docs / plans 建立可消费知识；
用 long-horizon loop 建立可持续执行；
用 trace grading / skill eval 建立可回归判断；
用 cleanup / doc gardening / follow-up PR 建立可持续收敛。

要把 agent 的成功标准写成可重复跑的 eval / trace graders，而不是只靠人工体验判断“这次看起来还行”。

证据状态

高共识（多个独立来源一致）

人类工程师的角色正在从直接编码转向环境设计、意图指定、反馈与审查。OpenAI InfoQ
多 agent 系统如果没有清晰结构和 ownership，会陷入锁竞争、重复劳动和漂移。Cursor self-driving codebases Cursor scaling agents
长期可用的 agent 工程体系必须依赖可观测性、文档系统、机械约束与评测闭环。OpenAI Agent evals Trace grading
长时程可靠性依赖持久项目记忆、计划文件和循环式验证，而不是单次长 prompt。Run long horizon tasks with Codex Modernizing your Codebase with Codex

单一来源（需谨慎，但很重要）

OpenAI 的 0 lines of manually-written code、约百万行代码、约 1500 个 PR、3.5 PRs / engineer / day 等具体数字，目前主要来自 OpenAI 官方自述。OpenAI
OpenAI 关于“每周五 20% 时间清理 AI slop”的描述，也是官方单一来源，但对理解 agent codebase entropy 很有价值。OpenAI

矛盾信息 / 表述差异

OpenAI 的文章更偏“单仓库 agent-first product engineering”，Cursor 的文章更偏“多 agent 大规模自治编排”。二者不是直接矛盾，而是强调层级不同：OpenAI 更像团队生产方式，Cursor 更像编排系统设计。
Benchmark 领域和生产系统领域也存在表述差异：公开榜单容易把焦点放在 % Resolved，而 OpenAI / Cursor 更重视真实工作流中的收敛、可恢复和可维护性。这不是冲突，而是评价维度不同。
OpenAI 的官方材料更强调 repo 内知识、计划文件、验证回路与团队工作方式；Cursor 的材料更强调 planner-worker 编排、吞吐与同步开销。两边互补后，harness engineering 的轮廓才更完整。

一句话总结

Harness engineering 说的不是“让 AI 帮你写代码”，而是“把软件工程重新组织成一个 agent 能稳定运行的系统”。它最相关的不是单个 demo，而是文档、约束、评测、观测、review、merge、cleanup 这些过去常被忽略、但在 agent 时代决定成败的基础设施。

参考来源

流程合规自检表

[x] 已检查当前工作区，未发现现成 survey sessions / harness engineering 调研文件
[x] 已并行调研 OpenAI 主文、Cursor 两篇主文及相关评测资料
[x] 已保留关键 URL
[x] 已保留关键原文摘录
[x] 已区分高共识 / 单一来源 / 表述差异
[x] 只交付一个最终 Markdown 文件