Author: @rohit4verse

You are not using the wrong model because you didn't find the right one AI.

You used it wrong AI because you did not build the correct environment.

Some teams have delivered millions of lines of code with three engineers, while other teams cannot even achieve a stable refactoring in the pipeline agent ——The reason is not the difference between GPT-5 or Claude Opus temperature setting or max tokens, not even the prompt word, although people have spent countless years arguing about the prompt word.

The difference is harness.

What this article is going to talk about is what this word means at the technical and conceptual levels——Because the entire industry has developed a bad habit: using this word carelessly.

harness is not a system prompt word, not a package for API call, not an evaluation framework, a prompt word template, nor a chatbot with a memory function.

harness is a complete design environment in which the language model operates, including the tools it can call, the format of the information it receives, how its history is compressed and managed, guardrails to catch errors before they cascade, and the scaffolding that allows it to hand off work to its future self without losing coherence.

When you look at Anthropic things built to make Claude Code really work, NLP Group in its landmark paper on agent-Computer interface SWE-agent , you'll start to see a similar pattern emerging from every team working seriously in this area.

Models are almost irrelevant. harness is everything.

Here is a brief introduction to how this concept has become a reality from 2025 to 2026 lang="EN-US"> AI Detailed technical analysis of engineering core insights. It covers relevant research, real-world implementation examples, failure modes that drive design decisions, and those patterns that come up again and again whether you're building programming agents, researching agents, or being a long-running autonomous software engineer.

After reading, you will not only understand harness what it is, but also why to build one correctly harness, has become the most valuable engineering skill in today's industry.

Part One: The Problem No One Talks

Why raw power is not enough

2024 In the middle of the year, AI A strange thing happened in the benchmarking field. Researchers began to notice that the same cutting-edge model could produce very different results on the exact same programming task, depending on how the task was presented and the tools available. The model has not changed, the underlying intelligence has not changed, only the interface has changed.

This should not be surprising. We've known for decades that the right tools can make engineers more productive. A software developer with a modern IDE, debugger, version control, and CI/CD pipeline is orders of magnitude more productive than the same person working in a pure terminal with just a text editor. IDEs don't make developers smarter; they reduce friction, surface information at the right time, catch errors early, and organize work into navigable units.

The same is true for language models. They are not general-purpose reasoning engines that reason from some infinite internal knowledge base, but sophisticated pattern matching engines that operate on tokens within a context window. Everything they know at a given moment is determined by the contents of the context window; everything they produce is conditioned on the structure of that context. The format of the input is not a decoration, it is the cognitive architecture of the agent .

Interfaces are not convenience layers. For language model agent , the interface is the mind itself.

This is the Princeton NLP Group 2024 published in SWE-agent The core proposition of the paper can withstand scrutiny. This paper introduces the concept of Agent-Computer Interface (ACI) and demonstrates a well-designed ACI produces 64% .

Same model, same task, same computational budget, the only variable is the interface.

Let this number settle for a moment. 64% is not the marginal benefit, it is the gap between effective tools and ineffective tools. And it comes entirely from the design of the environment, not from any improvements to the underlying model.

Context window is not a memory slot

A naive cognitive model for AI agent treats the context window as memory. You load the data, the model processes it, and you get the output. More context equals better performance, and longer prompts equal greater understanding. This mental model is wrong, and the wrong approach will destroy the agent you build upon it.

The context window is actually closer to the agent 's overall working awareness in a particular session. Each token in the window has a computational cost. Every piece of irrelevant information competes with relevant information for attention. The model does not have a selective attention mechanism that can cleanly ignore noise——The presence of noise will affect reasoning.

This has specific, measurable consequences for agent design. When you run grep inside a loop against a large code base and return ten thousand rows of matching results, you are not giving agent More information available, you are flooding its working memory with irrelevant data, which will reduce the quality of each subsequent step until the context is cleared.

When you want to see two functions because agent Use cat As you dumped the entire file out, you handed it a fire hose when it needed a glass of water.

SWE-agent 's researchers documented these failure modes in detail. The standard bash interface can cause agents to get stuck in repeated traversals: they will issue grep commands, get lost in what you are looking for, issue more grep commands, gradually fill the context with noise, and end up either giving wrong answers or stopping progress altogether.

The problem is not model intelligence, but that the interface has no mechanism to protect agent from being overwhelmed by itself.

ACI 's solution is to build a search tool that returns a capped, aggregated list of results. If your search returns more than 50 matches, the tool suppresses the output and tells the agent to narrow the query.

This design decision seems almost laughably simple in retrospect, but it is one of the most leveraged changes in the entire paper. It turns a failure pattern of context overwhelm into a natural cycle of refinement.

Part 2:SWE-Agent Paper and The birth of ACI

Agent-What exactly is a computer interface

ACI is defined in the SWE-agent paper as located in the language model An abstraction layer between agent and the computer environment. The analogy with human-computer interface (HCI) is intentional. Just as HCI research asks how to design interfaces that fit the cognitive architecture of human beings, ACI research asks how to design interfaces that fit the cognitive architecture of language models.

Human cognitive architecture involves visual pattern recognition, spatial memory, parallel attention across screens, and the ability to skim and selectively focus.

The cognitive architecture of language models is fundamentally different——It involves order token processing, sensitivity to contextual order and format, limited working memory, and a tendency to anchor on the most salient information in the cue word. Designing a good ACI means understanding these constraints and building around them, not against them.

There are four main components, each reflecting specific insights into how language models fail when gaining access to raw computers.

Search and Navigation

The search component replaces the standard grep and find command: 50 .

If a query exceeds this limit, the tool returns a message stating there are too many results and prompts the agent to refine its search. This sounds trivial, but is actually one of the most impactful decisions in the paper.

It is important because agents Like humans under cognitive load, they tend to continue their behavior when they feel uncertain. When one gets lost in a large code base, one searches wider and wider, creating more and more noise. Capped search tools disrupt this paradigm by creating a forcing function: you can't advance by being vague, you have to be precise. This drives the agent toward more prudent and targeted behavior.

File Viewer

The file viewer is the most concrete manifestation of the paper’s insights into cognitive architecture. The researchers tested a variety of viewer configurations and found that 100 rows per display was just the right number. Fewer lines (they tested 30 rows) results in agent Losing context for the surrounding code can lead to editing errors; having more lines (or showing the entire file) can cause the agent to become disoriented and miss important details.

Viewers are stateful, maintaining their position in the file between interactions. More importantly, it prepends each visible line with an explicit line number. This last detail may seem purely superficial, but it is not.

When agent needs to send a message to 47 to 52 line editing command, it needs to be able to read these numbers directly from the view, rather than counting rows or doing arithmetic. Removing this cognitive task from the agent's working memory frees up cognitive capacity for real problem solving.

File editor with Linting

The core innovation of the file editor is instant feedback with guardrails. The edit command accepts the starting line, ending line, and replacement text as a single operation. After each edit, the tool will automatically run linter on the modified file and report the results. If an edit introduces a syntax error, the edit is rejected before being applied, and the agent receives a clear error message showing both the original code and the failed edit.

This closes the feedback loop that causes cascading failures in naive agent implementation. When there is no linter , agent It's possible to introduce a syntax error, run the test suite, see a seemingly unrelated failure (because the real error is elsewhere), spend multiple steps chasing the wrong problem, and eventually exhaust the context window tracking a ghost.

Integrate linter directly into the editor, syntax errors can be caught the moment they are introduced, fixes are localized, and problems cannot be propagated.

Comparison of using the original bash tool: using sed or output redirection, there is no integrated feedback, editing is performed silently, and multi-line modifications require complex parameter formatting that is extremely error-prone. Agent may successfully run the command, but introduce a linter a subtle formatting error that could have been caught, and then spend the next ten steps wondering why the test failed.

Context management

The fourth component solves a problem that accumulates over long sessions: the accumulation of stale context. As the agent advances the mission, its history is filled with old observations, intermediate states, and exploration steps that no longer reflect the current state of the environment.

All this history takes up space in the context window and may be actively misleading agent by providing outdated information.

ACI 's context management system records earlier observations——The content before the last five rounds——Compressed into a single line summary. This focuses the active context on recent relevant information while preserving a compressed record of the overall trajectory.

Agent You can see what you have done recently and what your current status is at any time, without being overwhelmed by the complete uncompressed history of every command you have ever run.

Benchmark results and what they really mean

SWE-agent The paper is onSWE-bench dataset ACI was benchmarked against a dataset containing real GitHub Issues from popular Python code bases. The task is to receive a natural language bug report and produce a code patch to solve it. This is a difficult practical task that requires navigating an unfamiliar code base, understanding error messages, writing correct code, and verifying the fix.

Using GPT-4 With the standard bash shell Interface, the system solved the problem, the system solved 12.47% 's problems. This is the 64% relative improvement mentioned earlier, which comes entirely from interface design.

The researchers also performed ablation studies, removing components one at a time to isolate the contribution of each design decision. Linter The integration is always one of the most leveraged components; capped searches are critical to prevent context flooding; the stateful file viewer with line numbers significantly outperforms the original cat cat command and a simpler viewer design.

The performance difference has nothing to do with model intelligence and everything to do with cognitive load management. ACI reduces the amount of work required for models to track state, freeing up space for the work that really matters.

These revelations go far beyond programming agent . Any long-term agent task involves the same fundamental challenges: navigating a large information space, maintaining a coherent state across multiple steps, catching and recovering from errors, and managing the limited resource of contextual window attention. ACI 's design principles are generalizable. The specific tools will change, but the underlying problem structure will not change.

Part Three:Anthropic 's Harness Project (Long-running Agent Problems)

Why context window boundaries are the core puzzle

SWE-agent The paper solves the problem of how to design an interface for a single agent session. Anthropic 's engineering team is developing Claude Agent SDK and Claude In the process of Code , I encountered a different problem: What should I do if a task is too large to be completed within a single context window?

This is not a niche edge case. Most real software projects are too large to fit into any context window. A production-grade Web application contains hundreds of files, thousands of functions, test suites, configurations, documentation, and dependencies.

Even if you have a 20 million token context window, you cannot hold the complete project in your mind at the same time. Human engineers solve this problem through external memory, documentation, version control, and the understanding accumulated in the code base over weeks and months. And an agent that opens a new session has nothing.

The naive solution is compression (compaction), which works to a certain extent. Claude Agent SDK has built-in compression capabilities that can summarize old context when the window fills up. But compression alone is not enough.

Anthropic 's internal experiments show that even with compression mechanisms, like Opus 4.5

Failure presents two patterns, both of which are instructive.

The first failure mode istrying to do too much at once. When given "build a claude.ai clone"Such a prompt word, agent will try to complete the entire application at once.

It keeps implementing feature after feature, but each one is not completed or tested, exhausting the context window in the implementation process, leaving the next session with a half-finished application—There is no documentation of what has been completed, nor any clear explanation of the current state of the code.

The next agent instance will spend most of its context budget making sense of the mess rather than moving forward.

The second failure mode occurs later in the project. After some functionality has been built, subsequent instances of the agent will look around, see that progress has been made, and conclude that the work is done"'s conclusion. It will declare victory and stop working when the application is only half complete.

This is not stupidity, but a reasonable inference from incomplete information. Agent There is no structured way to learn about this project"Complete"What exactly does it mean.

Both failures have a common root:the agent does not have a persistent, structured understanding of the project state that cannot survive context window boundaries and provide direction for subsequent sessions.

Double Agent Architecture: Initialization Agent and Programming Agent

Anthropic 's solution was a two-part architecture that has since become a template for teams that are serious about long-term agentic work.

The first part isInitialization Agent. This is a specialized initial session with a dedicated system prompt word, and its entire purpose is to set up the environment in which all subsequent programming agent will operate.它不编写功能，它创建使得跨多个后续会话的功能开发成为可能的脚手架。

初始化 Agent 产出三个关键输出。

首先，它创建一个能够可靠启动开发环境的init.sh 脚本。这听起来平淡无奇，但具有显著的杠杆效益。

后续每一个编程agent 会话都可以通过运行 init.sh 来开始，而不必花费 token 去摸索如何启动服务器、配置数据库、将应用调整到可测试状态。在每次会话中节省的这部分开销，积累起来不容忽视。

其次，初始化 Agent 创建一个全面的功能列表文件。在 Anthropic 内部运行的 claude.ai 克隆实验中，这意味着超过 200 条具体的端到端功能描述，例如"用户可以打开一个新对话，输入查询，按下回车，并看到 AI 的回复"。每个功能最初都被标记为失败。

这个文件是项目的基准事实。一个开启新会话的编程agent 读取这个文件，就能立刻确定无疑地知道哪些东西已经构建完成、哪些尚未完成。它无法环顾四周，看到一些代码，就得出工作已完成的结论——功能列表会告诉它真相。

第三，初始化 Agent 创建一个 claude-progress.txt 文件并进行初始的 git 提交。进度文件是一个人类可读的日志，agent 在每次会话结束时更新它，记录自己处理了什么、完成了什么、以及将事情留在了什么状态。结合 git 历史记录，每一个后续编程 agent 都能快速定向，而无需将上下文预算耗费在考古工作上。

第二部分是编程 Agent。 初始化之后的每次会话使用不同的提示词：一次只处理一个功能，将环境留在干净的状态，并在会话结束前更新进度文件和 git 历史。增量推进，记录状态，干净交接。

功能列表作为认知锚点

功能列表值得特别关注，因为它解决了一个容易被低估的问题。没有它，在复杂代码库中运作的 agent 必须从代码本身推断项目的完成度。这种推断是不可靠的。

代码可能存在但并不可用；功能可能存在但并不完整。一个阅读代码并推断完成情况的 agent，会频繁得出错误答案，严重到足以构成问题。

功能列表使完成度变得明确无歧义。每个功能都有一个passes 字段，值为 true 或 false。 Agent 要么在端到端验证某功能可用后更新这个字段，要么不更新。没有歧义，不需要推断，基准事实就在文件里。

Anthropic 有意将这个列表存储为 JSON 而非 Markdown。原因是行为层面的。从经验来看，模型对 JSON 文件的不当修改或覆写概率，低于对 Markdown 文件的概率。

JSON 具有抵制随意编辑的刚性结构。这是一个细节，但后果真实存在：你希望功能列表是agent 谨慎更新的东西，而不是它心血来潮随意改写的东西。

{"category": "functional",

"description": "新建对话按钮创建一个全新的会话",

"steps": ["导航到主界面",

"点击"新建对话"按钮",

"验证新会话已创建",

"检查对话区域显示欢迎状态",

"验证对话出现在侧边栏中"],

"passes": false}

伴随此格式的指令是明确的：删除或编辑测试是不可接受的，因为这可能导致功能缺失或存在缺陷。你提示模型将这个文件视为不可侵犯的。 JSON 结构在架构层面强化了这一指令。

增量推进与干净状态要求

多会话 agentic 工作中最困难的问题之一，是确保每次会话结束时都处于一个下一次会话可以安全地在其上构建的状态。

若无明确的执行机制，agent 倾向于将工作留在上下文窗口填满时碰巧所处的状态：半成品功能、破损的测试、未记录的变更。下一个 agent 继承的是这团乱麻。

Anthropic 的解决方案是将干净状态作为一等要求，而非可有可无的附加项。每次编程 agent 会话以一次 git 提交（附有描述性信息）、对进度文件的更新以及在必要时回退到可工作状态为结尾。

他们所说的"干净状态"，意味着代码适合合并到主分支：没有重大缺陷、有良好文档、处于一个开发者可以合理地开始新功能而无需先解开他人半成品工作的状态。

git 提交不只是一个检查点，它是一个恢复机制。当 agent 做出破坏某些东西的变更时，它可以用 git 回退到最后已知的良好状态并重试。这正是人类工程师的工作方式，事实证明对 agent 同样是正确的纪律。版本控制是认知脚手架，而不仅仅是源代码管理。

测试：无人愿意谈论的失败模式

Anthropic 记录了一种几乎在每个认真的 agentic 编程项目中都会出现的失败模式：agent 在没有端到端验证的情况下将功能标记为完成。

Agent 会做出代码变更，对开发服务器运行单元测试或 curl 命令，看到通过结果，然后将功能标记为已完成。但当以用户方式通过浏览器测试时，该功能实际上并不可用。

单元测试成功与端到端功能可用之间的差距，是人类工程师通过切换上下文来跨越的——运行应用并尝试使用它。一个没有明确浏览器测试能力的 agent 无法完成这种切换。

它只能观察其工具所允许观察的内容，如果这些工具不包括浏览器自动化，它就会持续遗漏一类只在真实用户流程中显现的缺陷。

解决方案是为 agent 提供访问 Puppeteer MCP 服务器的能力——一个浏览器自动化工具，允许 Claude 实际导航应用、点击按钮、填写表单，并验证功能端到端可用。

性能提升是显著的。仅从代码中不可见的缺陷，当 agent 能够看到用户所见的内容时，变得一目了然。

这是一个通用原则的具体例证：agent 工作的质量受限于其反馈回路的质量。如果你的 agent 无法在真正重要的领域中观察到其行为的后果，它就会对代理指标进行优化，而这些指标可能与实际正确性并不相关。

启动流程：快速进入状态

Anthropic harness 中每次编程 agent 会话都以一套标准化的启动流程开始，其目的是在不浪费 token 的前提下尽快为 agent 定向。该流程如下：

运行pwd 确认工作目录；读取进度文件和 git log 以了解近期工作；读取功能列表并选择优先级最高的未完成功能；运行init.sh 脚本启动开发环境；运行基本的端到端测试以验证应用处于可工作状态。

只有完成所有这些步骤之后，agent 才会开始处理新功能。如果启动测试显示应用已损坏，agent 会在触碰任何新内容之前先修复已有问题。这防止了一种复合问题：agent 在破损的基础上开始新功能，使底层问题更难被隔离和修复。

启动流程还以一种具体的方式节省了 token：因为 init.sh 脚本精确记录了如何启动开发环境，agent 不需要从头摸索。每次会话在环境配置上节省的 token，在一个漫长项目中积累起来相当可观。

[助手] 我将首先确认方向，了解项目的当前状态。

[工具调用]

[工具调用]

[工具调用]

[助手] 让我检查 git log 以查看近期工作。

[工具调用]

[助手] 现在让我检查是否有 init.sh 脚本来重启服务器。

<启动开发服务器>

[助手] 很好！现在让我导航到应用，验证一些基本功能仍然正常运行。

<测试基本功能>

第四部分：OpenAI 的 Harness 工程（零行手写代码）

这场实验

2025 年 8 月下旬，OpenAI 的Codex 团队以一个唯一的约束条件创建了一个 git 代码库：无人工编写代码。代码库中的每一行代码——包括应用逻辑、测试、CI 配置、文档、可观测性工具和内部开发者实用工具——都将由 Codex agent 编写。人类负责引导，agent 负责执行。

五个月后，该代码库在上述所有类别中共包含约一百万行代码。大约 1500 个 PR 已被提交并合并。一个由三名工程师组成的小团队推动了其中大部分工作，平均每名工程师每天提交 3.5 个 PR。

随着团队扩充至七名工程师，每名工程师的吞吐量实际上还有所提升。该产品拥有数百名每日活跃的内部用户和外部 alpha 测试者。

这不是演示，而是一个完全通过 agent 生成代码构建和交付的真实内部产品。团队于 2026 年 2 月撰文描述了这段经历，其核心信息与 SWE-agent 论文一致：瓶颈从来不在模型能力，瓶颈始终在于环境设计。

工程工作的重新定义

OpenAI harness 工程文章中最重要的观察，是关于工程工作本身的变化。当你的主要工作不再是编写代码，你在做什么？

你在设计环境。你在明确意图。你在构建反馈回路。你在持续追问的不是"我如何修复这个缺陷？"而是"环境中缺少什么能力，导致这个缺陷反复出现？"

当某些东西失败时，修复方案几乎从来不是"更努力尝试"，而几乎总是"环境中缺少或配置错误了什么结构性要素，导致 agent 在这里失败？"这是工程思维的深刻转变：你不再调试代码，你开始调试产生代码的系统。

工程团队的首要工作变成了使 agent 能够完成有用的工作，而不是亲自完成这些工作。

在实践中，这意味着：将宏大目标分解为更小的构建模块，构建使这些模块可实现的工具和抽象，以及将失败作为信号，了解环境需要在哪些方面提供更好的支持。

人类工程师采用深度优先的工作方式：当 agent 卡住时，他们不会试图亲自编写代码，而是追问缺少什么，将其构建进环境，然后让agent 再次尝试。

代码库知识作为系统记录

OpenAI harness 中最重要的架构决策之一，是将代码库本身作为 agent 所需了解的一切内容的唯一真实来源。其洞察简单却意义深远：

从agent 的视角来看，任何它在运行时无法在上下文中访问的内容，实际上都不存在。存在于 Google 文档、Slack 消息线程或某人脑海中的知识，对系统而言是不可见的。

在项目早期，团队尝试了"一个大 AGENTS.md"的方案——一个单一的大型指令文件，包含 agent 需要了解的关于项目、架构、规范和约束的一切。它以可以预见的方式失败了，且以四种值得理解的方式失败。

第一，上下文是稀缺资源。一个庞大的指令文件挤占了任务、代码和相关文档的空间。 Agent 要么遗漏关键约束，要么开始为错误的目标优化。

第二，过多的指导变成了无指导。当一切都被标记为重要，就什么都不重要了。 Agent 开始局部模式匹配，而不是有意识地导航。

第三，它会瞬间腐化。随着代码库的演进，一体化手册变成了过时规则的坟场。

第四，它难以验证。一个单一的文本块不适合进行覆盖率检查、新鲜度追踪或交叉链接，漂移是不可避免的。

解决方案是一个被视为系统记录的结构化docs/ 目录，配合一个简短的 AGENTS.md 文件（约 100 行）作为地图，指向其他地方更深层的真实来源。

设计文档经过了分类和索引；架构文档提供了领域和包层次的顶层地图；计划被视为第一等制品，其进度和决策日志被提交进代码库。

这实现了团队所称的渐进式披露：agent 从一个小而稳定的入口点出发，被引导去知晓下一步该看哪里，而不是一开始就被淹没。结果是 agent 能够直接从代码库推断整个业务领域，无需访问可能不可用或可能已过时的外部上下文。

应用可读性：让系统对 Agent 可见

随着代码生成吞吐量的增加，瓶颈从生成转移到了验证。团队生成代码的速度超过了人工 QA 的验证能力。解决方案是通过让应用对 Codex 直接可读，使更多的验证工作成为 agent 能够自行完成的事情。

这涉及若干具体投入。他们使应用能够按 git worktree 启动，让 Codex 能够为它正在处理的每个变更启动并驱动一个应用的独立实例。

他们将 Chrome DevTools Protocol 接入 agent 运行时，并创建了处理 DOM 快照、截图和浏览器导航的工具。这使 Codex 能够直接复现缺陷、验证修复，并对 UI 行为进行推理，而不需要人类与应用交互。

他们构建了一套完整的本地可观测性技术栈：通过 LogQL、PromQL 和TraceQL 向 Codex 暴露日志、指标和追踪。

每个agent 任务都运行在一个完全隔离的、拥有独立可观测性数据的应用版本上，任务完成后即被销毁。这意味着agent 可以使用真实的可观测性工具调试类生产环境问题——与人类工程师使用的工具相同——而不必仅凭代码推断行为。

这里的原则与 SWE-agent 论文所论证的相同：agent 工作的质量受限于其反馈回路的质量。如果 agent 能看到用户所见的内容，并能观察到人类工程师所观察的相同指标和日志，它就能捕获并修复比仅能操作代码的 agent 宽得多的一类问题。

在不微观管理的情况下执行架构

在一个完全由 agent 生成的代码库中，随着时间推移维护架构一致性是最有趣的挑战之一。 Codex 会复制代码库中已存在的模式，包括不均匀或次优的模式。

久而久之，这会导致漂移：糟糕的模式扩散，不一致性积累，代码库对未来的 agent 运行变得更难正确导航。

OpenAI 的解决方案是机械化地执行不变量，而非依赖人工代码审查。应用围绕一个刚性的架构模型构建：每个业务领域划分为固定的层次集合，具有经过严格验证的依赖方向和有限的允许边界集合。

这些约束由自定义 linter（自然是由 Codex 编写的）和结构测试来执行。

核心洞察是执行边界，同时允许边界内的充分自由。 Linter 检查代码是否沿正确方向流经层次结构，但不规定边界内特定功能如何实现。这与平台团队在规模化时保持有效性的原则相同：执行基础，在其上允许自主。

这些 linter 是专门为 agent 生成有用错误消息而定制编写的。当 linter 捕获到一个违规时，错误消息包含格式化为可注入 agent 上下文的修复指令。这形成了闭环：被违反的约束、被违反的规则，以及修复步骤，全部在单一的可操作反馈消息中一并传递。

他们还将所谓的"黄金原则"直接编码进代码库：有主见的、机械化的规则，使代码库对未来的 agent 运行保持可读性和一致性。优先使用共享工具包而非手写辅助函数，在边界处验证数据形状。

这些原则通过周期性运行的后台清理任务来执行——扫描偏差、更新质量评级、提交针对性的重构 PR。其中大多数可在一分钟内完成审查并自动合并。

吞吐量改变了合并哲学

当 agent 吞吐量大幅超过人类注意力容量时，传统工程规范会变得适得其反。等待审查的PR 阻塞了 agent 的工作；逐一调查的测试偶发性失败消耗了本可用于更高杠杆任务的人类注意力。

OpenAI 的团队做出了一个有意为之的决定：以最小的阻塞合并门控来运作。 PR 保持短生命周期，测试偶发性失败通过重新运行来处理，而非无限期阻塞进度。

当agent 吞吐量远超人类注意力时，纠错是廉价的，等待是昂贵的。这个权衡在低吞吐量环境中看起来不负责任，在高吞吐量环境中则显而易见。

这对向 agent 驱动开发转型的团队而言是一个真正重要的洞察。当人类工程师亲自编写每一行代码时合理的合并哲学，在 agent 每名工程师每天生成 3.5 个 PR 时并不自动适用。瓶颈发生了转移，流程也需要随之转移。

第五部分：Awesome Agent Harness 分类体系

生态系统图谱

由 GitHub 上AutoJunjie 项目维护的 Awesome Agent Harness 代码库，试图绘制 harness 工程工具链这一新兴生态系统的全景图。在深入分类体系之前，有必要先明确其核心论点：AI 编写代码的能力实际上已经是一种商品。

基础模型可以生成可运行的代码，这不再是差异化能力。真正的差异化能力在于协调机制与环境设计。

该代码库将一个严肃的 agent harness 生态系统所需的完整技术栈划分为七个不同层次。理解这些层次，有助于解释为何"构建一个 AI 编程助手"实际上是许多相互独立的工程问题，而非一个单一问题。

第一层：人类监督

位于最顶层的是人类监督层，由人类负责审批提案、审查 PR、设定优先级。这在传统意义上并非一个技术层，而是人类判断与 agent 执行之间的接口。

此处的核心设计原则是：工程师应当负责设计环境、审查产出，而非直接编写代码。他们的杠杆来自于引导，而非执行。

第二层：规划与需求（Spec 工具）

这一层将人类的想法转化为结构化规格说明和任务 DAG（有向无环图），供 agent 可靠地消费执行。

其底层洞察在于：agent 是盲目执行的。如果规格说明模糊或存在歧义，agent 会按其自身的理解来产出结果，而这往往与人类的真实意图相悖。 Spec 工具在代码编写之前的需求阶段强制要求精确性。

该领域中的一个项目 Chorus，试图解决代码库所称的"反向对话缺口"。它并非让人类来撰写详细的规格工单（这是一个重大故障点，因为人类在 agent 所需的精确程度上并不擅长），而是让 AI 来提出任务 DAG 并细化需求，人类则在执行开始前扮演严格的验证与审批角色。

AI 从局部意图生成完整规格说明的能力，强于人类从零开始撰写的能力。

第三层：全生命周期平台

这类工具管理从初始需求到最终交付的端到端流程，将 AI 提案与人类验证关卡及子 agent 编排整合为一体。它们是规格层与执行层之间的粘合剂，负责处理整个开发生命周期中的状态管理。

第四层：任务运行器（Task Runners）

任务运行器弥合了问题追踪系统（GitHub Issues、Linear）与编程 agent 之间的鸿沟。其工作流如下：

由人类或 PM agent 创建 Issue，任务运行器生成工作空间，agent 交付 PR，人类进行审查。

这一类别中的工具包括：持续轮询任务队列、决定何时启动 agent、以及在无需人工介入执行循环的情况下完成工作交付的各类系统。

第五层：Agent 编排器

编排器通过在独立的 git worktree 中隔离各 agent 的工作，实现多 agent 并行执行，从而解决吞吐量问题。

这一点至关重要——如果多个 agent 并行工作时共享同一工作空间，彼此之间必然会产生冲突。 Git worktree 隔离为每个 agent 提供了独立的沙箱，使多个 agent 能够同时工作而互不干扰。

Vibe Kanban、Emdash、Composio 等工具均实现了这一模式。每个 agent 任务拥有独立的 git worktree，变更在隔离环境中得到验证后方可合并。

CI 反馈、合并冲突以及 agent 间的协调，均由编排层统一处理，无需人工干预。

第六层：Agent Harness 框架与运行时

框架提供用于构建自定义环境的可组合原语：渐进式披露机制、子 agent 生成、结构化上下文分发。运行时则提供持久化基础设施：长期记忆、定时执行、会话间多通道通信。

框架与运行时的区别至关重要。 框架是你在其上构建的东西，运行时是持续运行的东西。

Claude Agent SDK 主要是一个框架。而一个按 cron 计划运行 agent、跨会话维护持久记忆、处理 agent 实例间多通道协调的系统，则是一个运行时。两者对于严肃的长期 agentic 工作而言缺一不可。

第七层：编程 Agent

位于最底层的是执行层：Claude Code、Codex 及类似系统，负责编写、测试和调试代码。代码库的核心洞察在于：这一层是商品化的。 Agent 的有效性主要由技术栈中其上方的所有层级决定，而非 agent 本身。

这一颇具挑战性的论断有充分的证据支撑。 SWE-agent 论文通过实验验证了这一点：相同的模型，仅凭界面设计改进便带来了 64% 的性能提升。

OpenAI 的Codex 团队从实际操作层面验证了这一点：真正重要的工程工作是环境设计，而非执行本身。 Anthropic 的 harness 工程实践从实操层面验证了这一点：初始化 agent 的配置决定了编程 agent 能否顺利推进工作。

第六部分：反复出现的设计模式

纵观所有这些系统和组织，若干设计模式反复出现。这并非巧合，而是在尝试大规模可靠部署agent 时涌现出的问题所对应的工程解决方案。

模式一：渐进式披露（Progressive Disclosure）

不要预先将 agent 可能需要的所有信息一次性提供。给它定向所需的最小信息量，并提供必要时获取更多信息的指引。这一模式在以下场景中均有体现：

SWE-agent 的搜索结果上限（不返回全部结果，迫使 agent 进行精炼）、OpenAI 的 docs/ 架构（简短的地图指向更深层的内容）、Anthropic 的启动流程（先读进度文件，再读功能列表），以及实现结构化上下文分层的harness 框架。

采用这一模式的认知原因在于：上下文是有限资源，agent 的注意力并非均匀分布其间。位于提示词开头的信息具有不成比例的影响力。一个简短、聚焦的入口点，指向更丰富的上下文，比稀释注意力的大而全的信息堆砌更为有效。

实践原因在于可维护性。一个作为更深层文档地图的简短入口点，是可以保持准确的；而一个包罗万象的单体文档则会迅速变得陈旧，并产生反效果。

模式二：Git Worktree 隔离

一个 agent，一个worktree。这一模式出现在每一个严肃的编排系统中。其逻辑是直接的：当多个 agent 并行工作（或单个 agent 按序执行任务）时，需要在工作流之间保持隔离。若无隔离，并行 agent 会相互覆盖彼此的变更。

即便是顺序执行的 agent，也需要能够在隔离环境中验证变更，再将其影响扩散到主代码库。

Git worktree 在文件系统层面提供这种隔离。每个 agent 拥有独立的工作目录、独立的分支和独立的环境。

变更在隔离环境中产生、在隔离环境中测试，仅在通过验证后才被合并。这正是现代 CI/CD 系统为人类工程师所采用的模式，同时也被证明是 agent 编排的正确模型。

模式三：规格优先，代码库作为系统记录

Agent 对非正式知识是盲目的。任何存在于 Slack 消息、Google 文档或某人脑海中的信息，对 agent 而言都是不可见的。 Agent 能够处理的只有其上下文窗口中的内容，而该上下文的唯一可靠来源就是代码库。

这一模式体现为：Anthropic harness 中的功能列表文件、OpenAI 系统中结构化的 docs/ 目录、各开源框架中的 AGENTS.md 文件，以及 awesome-agent-harness 分类体系中的 spec 工具层。

共同主线是：规格说明、需求、架构决策和约束条件，必须在执行开始前编码为代码库中的机器可读文件。 如果 agent 无法从代码库中读取，它便不存在。

这对工程团队的文档工作方式具有重要含义。文档不再仅仅是为人类读者服务。它是人类意图对agent 可见的机制。模糊、陈旧或存储在代码库之外的文档，是积极损害 agent 性能的文档。

模式四：机械化架构执行

人工代码审查无法扩展到 agent 驱动的开发场景。当 agent 每名工程师每天能够提交 3.5 个 PR 时，审查不能成为维护代码质量和架构完整性的主要机制。解决方案是将架构约束编码为自动运行的机械化检查。

自定义 linter、结构测试和 CI流水线，取代了人工驱动开发中代码审查所承担的大部分功能。

机械化检查的优势在于：一致性强、速度快，并能在违规发生点提供即时反馈。一个捕捉到架构违规并在错误信息中返回修复指令的 linter，比三天后在 PR 评论中才捕捉到同一问题的代码审查者更为有效。

核心设计原则是执行不变量，而非实现细节。你深切关注的是依赖方向、边界跨越、接口处的数据校验以及命名与结构的一致性。

而 agent 使用哪个具体库、如何分解某个函数，只要满足行为契约，你并不在意。这在定义良好的结构内给予了 agent 充分的自主空间。

模式五：闭合的反馈回路

所有高性能的 harness 架构都将反馈回路收紧到极致。 linter 在编辑时捕获语法错误；运行时错误通过 agent 可查询的可观测性工具浮现；UI 缺陷通过 agent 可驱动的浏览器自动化工具发现；测试失败则附带上下文信息，说明哪里出了问题。

与之相对的另一种方式——agent 编写代码，在外部进行测试，在后续会话中才获得失败反馈——速度更慢、token 消耗更多，也更容易产生级联失败。反馈回路中每一个能够缩短行动与结果之间间隔的节点，都是可以提升 agent 性能的节点。

这是 harness 对于经典软件工程原则"尽早捕获错误"的具体演绎。错误发现得越早，修复成本越低。对 agent 而言，这一原则更具强制性——未被即时捕获的错误会在上下文中累积，并降低后续推理的质量。

第七部分：这对工程师究竟意味着什么

可迁移的技能

harness 工程这一学科，本质上是将系统思维应用于 agent 环境。它要求你对语言模型的认知架构有足够深入的理解，从而能够设计出顺应其运作机制而非与之对抗的环境。

它要求你以分布式系统工程中熟悉的方式来思考状态管理、反馈回路、错误恢复和上下文优化，只不过将其应用于一个全新的领域。

在这一新兴范式中最为高效的工程师，并不是那些拥有最佳提示词技巧的人——尽管提示词确实重要。

他们是那些理解整个系统运作方式的人：上下文如何流动、在哪里遭到污染、如何收紧反馈回路、如何跨会话保持状态，以及如何在不微观管理 agent 行为的前提下执行约束。

抽象地看，这些并非全新的技能，而是优秀软件工程师已有技能的延伸：系统设计、API 设计、错误处理、测试策略。真正新颖之处在于领域的转换：从为人类设计接口，转变为为语言模型 agent 设计环境。

你应该追问的问题

当你构建的 agent 系统出现问题时，harness 工程思维会引导出一套与朴素思维截然不同的问题。

与其问"我怎么写出更好的提示词？"不如问"agent 当前无法获取哪些它所需要的信息？

"与其问"为什么模型会犯这个错误？"不如问"缺少哪个反馈回路，导致这个错误在传播之前未能被捕获？

"与其问"agent 为什么没有按我说的去做？"不如问"环境中存在什么约束，阻止了 agent 执行我的指令？"

这种转变不只是语义层面的。它改变了你投入工程精力的方向。为某个特定故障模式设计更好的提示词，是局部的、临时的。构建能够预防一类故障模式的更好工具，是通用的、永久的。 harness 正是这种永久性投资的载体。

执行层的商品化

awesome-agent-harness 代码库核心论点中有一个令人不安的含义，值得直白地说出来。如果执行层是商品化的，那么 AI 驱动开发中的长期竞争壁垒就不在于模型本身，而在于 harness。

这意味着，那些投资于 harness 工程——构建脚手架、反馈回路、可观测性、规格工具以及使 agent 能够大规模可靠工作的编排系统——的组织和个人，将相较于那些主要专注于选择何种模型或如何提示的人，拥有持久的优势。

OpenAI 的 Codex 团队为其特定代码库和领域构建了相当于自定义开发平台的东西。 Anthropic 构建了一套 harness 架构，使其能够在复杂应用上实现数月的持续进展。 SWE-agent 团队构建了一套界面，使相同模型产出提升了 64% 的结果。这些优势没有一个来自模型本身，它们全部来自环境。

模型负责思考，harness 决定思考什么。把这个区别理解清楚，才是真正理解了这场游戏的全部。

第八部分：构建你自己的 Harness

最小可用 Harness

你不需要构建 OpenAI 的可观测性技术栈，也不需要 Anthropic 完整的双 agent 架构，就能从 harness 思维中获益。一个真实项目中针对编程 agent 的最小有效 harness，只需要少数几个核心组件。

从持久化进度文件开始。让 agent 在每次会话开始时读取它，以了解上次做了什么；在每次会话结束时写入它，以记录本次的工作。这一个单一改变，就能防止"过早宣告完成"的失败模式，并确保跨上下文窗口边界的工作连续性。

添加结构化任务列表。不是对项目的模糊描述，而是具体的、可枚举的、可验证的完成标准列表。每一项都应描述一个可端到端测试的用户可见行为，并标注状态——agent 只有在完成验证后才能更新该状态。这能防止"做了一半看起来像做完了"的失败模式。

将带有描述性提交信息的版本控制作为每次会话的一等公民。每次会话以一次提交结束。在代码提交且进度文件更新之前，agent 不应认为工作已完成。这创造了干净的交接，使多会话工作具有连贯性。

如果你在构建 Web 应用，请添加浏览器自动化。一个只能读取代码的 agent 与一个能够实际使用所构建应用的 agent，其差距，等同于一个只能读代码的开发者与一个能够运行应用的开发者之间的差距。大多数真正重要的 bug，只有在运行时才能显现。

环境审计

如果你已有一套 agent 系统但表现欠佳，harness 工程方法建议采用一套特定的诊断流程。不要急于寻找更好的模型或更长的提示词，而是做一次环境审计。

追问：agent 需要哪些它目前无法获取的信息？在任务流程中，agent 经常在哪些节点卡住或犯错？缺少什么反馈，导致 agent 无法自行捕获这些错误？上下文在哪里被无关信息污染？有哪些约束目前依赖 agent 的自我判断来执行，而应当被强制检查所取代？

每一个问题都指向一个具体的 harness 改进方向。信息缺失，变成代码库中的新工具或新文档；反馈缺失，变成新的测试、linter 或可观测性集成；上下文污染，变成新的上下文管理策略；未被执行的约束，变成新的机械化检查。

这是 harness 开发的良性循环：每一次失败都是环境需要改进的信号，而每一次环境改进都会降低该失败在未来所有 agent 会话中出现的频率。

最后一件事

变革性技术在早期阶段被误读，往往存在一个共同的规律。吸引公众眼球的东西——原始能力、令人印象深刻的演示、跑分成绩——鲜少是决定长期胜负的因素。基础设施层、harness、环境，通常才是真正价值被创造和捕获的地方。

Web 的变革性，不在于 HTML 的存在，而在于搜索引擎和浏览器让 Web 变得可导航。移动端的变革性，不在于智能手机的存在，而在于应用商店和开发者工具使得大规模地在智能手机上构建应用成为可能。在这两个案例中，组织和整合底层能力的平台层，才是持久价值的所在。

AI agent 正在遵循同样的规律。能力已然存在。问题是谁来构建让这种能力变得可靠、可控、持续可改进的环境。

SWE-agent 的研究者在 2024 年理解了这一点，并用数据加以证明。 Anthropic 在构建 Claude Code 时理解了这一点，并公开记录了下来。

OpenAI 在构建其内部产品时理解了这一点，并分享了相关经验。 awesome-agent-harness社区正在数十种工具和框架中对此进行系统性整理。

harness 就是一切。  模型是推理引擎，harness 是上下文、约束、反馈回路、记忆、工具和脚手架——它们共同决定推理引擎究竟能够完成什么。

把 harness 做对，不是一个提示词工程问题，而是一个系统工程问题。这是当前应用 AI领域最重要的工程问题。

请以此为指引，去构建。