原文链接:https://x.com/0xwhrrari/status/2093685107534000560
作者：rari（@0xwhrrari）· 全文中文，紧随其后的引用块为英文原文对照。
大多数人面对一个不听话的 agent，第一反应是改提示词。然后是换模型。然后是塞一个更大的上下文窗口。
Most people respond to a failing agent by changing the prompt. Then they change the model. Then they add a larger context window.
可 agent 照样忘记之前的决定。照样用错工具。照样跳过验证。照样卡在同一个死循环里。
The agent still forgets decisions. It still uses the wrong tool. It still skips verification. It still gets stuck in the same loop.
问题往往不在智力。问题在它周围的环境。那个环境就是 harness。设计这套环境，就是 harness engineering。
The problem is not always the intelligence. The problem is the environment around it. That environment is the harness. And designing it is harness engineering.
Anthropic CEO Dario Amodei 在讲 Claude Code 是怎么长出来的时候，说得很直接：
Dario Amodei, CEO of Anthropic, said it directly while explaining how Claude Code emerged.
“当然，你需要一个界面，你需要一套 harness 才能用它们”
“Of course, you need an interface, you need a harness to use them”
我在 Substack 上写关于 AI agent、工作流和生产系统的实操拆解。点这里订阅 newsletter
I publish practical breakdowns of AI agents, workflows, and production systems on Substack. Join the newsletter here
READ FILES allowed by default
RUN TESTS allowed inside sandbox
WRITE FILES allowed inside workspace
ACCESS NETWORK scoped by task
DEPLOY requires approval
DELETE DATA requires approval
模型只是推理引擎
The model is only the reasoning engine
模型可以说出下一步该做什么。
A model can suggest the next action.
它没法自己造出一个可靠的操作环境。
It cannot create a reliable operating environment by itself.
harness 决定模型能看见什么、能碰什么、什么能跨会话存活、什么算证据、以及什么时候必须停下。
The harness decides what the model can see, what it can touch, what survives between sessions, what counts as evidence, and when the run must stop.
{
"goal": "ship the feature",
"inputs": ["issue", "repository", "design"],
"output": "reviewable pull request",
"constraints": ["no schema changes", "preserve public API"],
"done_when": ["tests pass", "visual check passes", "review passes"]
}
提示词只是这套系统里的一个组件。
The prompt is one component inside this system.
模型是另一个。
The model is another.
产品是周围每个组件都配合起来时发生的那个东西。
The product is what happens when every surrounding component works together.
prompt engineering 改善的是指令。
harness engineering 改善的是指令被执行时的条件。
Prompt engineering improves the instruction.
Harness engineering improves the conditions under which the instruction is executed.
同一个模型可以变成完全不同的 agent
The same model can become a completely different agent
把同一个模型放进一个聊天框，它只会回答问题。
Put the same model inside a chat box and it answers questions.
把它放进一个有终端、有测试、有浏览器工具、有项目记忆、有隔离 worktree、有评审循环的仓库里，它就能交付软件。
Put it inside a repository with terminal access, tests, browser tools, project memory, isolated worktrees, and a review loop and it can ship software.
权重没变。
The weights did not change.
变的是 harness。
The harness did.
OpenAI 用 Codex 搭 agent-first 代码库时，描述了同一次转变。
OpenAI described the same shift while building an agent-first codebase with Codex.
他们早期进展缓慢，是因为环境定义得不充分，而不是因为模型缺少原始能力。
Their early progress was slow because the environment was underspecified, not because the model lacked raw capability.
应对方式不是让 agent「再努力一点」。
The response was not to tell the agent to try harder.
而是问：缺的是哪项能力，然后把这项能力变得既可读、又可强制执行。
It was to ask what capability was missing and make that capability both legible and enforceable.
“环境定义得不充分”
OpenAI，《Harness engineering: leveraging Codex in an agent-first world》
“The environment was underspecified”
OpenAI, Harness engineering: leveraging Codex in an agent-first world
这就是核心想法。
This is the central idea.
当 agent 反复失败，别再去改提示词里的形容词。
When an agent fails repeatedly, stop editing adjectives in the prompt.
去检查模型周围的系统。
Inspect the system around the model.
https://openai.com/index/harness-engineering/
一个生产级 harness 有七件事要做
A production harness has seven jobs
1. 把请求变成契约
1. Turn the request into a contract
在 agent 动手之前，把请求转换成一个有边界的对象。
Before the agent acts, convert the request into a bounded object.
契约保护任务不被悄悄改写。
The contract protects the task from silent redefinition.
没有它，agent 可以完成另一件完全不同的事，然后照样宣布成功。
Without it, the agent can complete a different job and still declare success.
2. 给 agent 一张地图
2. Give the agent a map
agent 需要项目知识。
Agents need project knowledge.
但它不需要每个上下文窗口里都塞满所有文档。
They do not need every document in every context window.
用一个简短的根级指南，告诉 agent 该去哪里找。
Use a small root guide that tells the agent where to look.
{
"context_sources": ["issue", "repo_map", "design_spec"],
"policy_version": "v12",
"model_route": "complex_coding",
"tools_used": ["shell", "browser", "tests"],
"tests": { "passed": 42, "failed": 0 },
"human_corrections": 1,
"retries": 2,
"cost_usd": 3.84,
"accepted_artifact": "pr_1842",
"rollback_point": "commit_7f3a"
}
地图保住上下文。
A map preserves context.
一本巨型说明书会把上下文吃光。
A giant manual consumes it.
把细节知识放在它所管辖的代码、工具或工作流旁边。
Keep the detailed knowledge close to the code, tool, or workflow it governs.
只在当前任务真的需要时才加载。
Load it only when the current task needs it.
GUIDE
"UI code may not query the database directly"
CHECK
lint fails when UI imports the repository layer
3. 把对的工具放进对的环境
3. Expose the right tools inside the right environment
工具不是一排按钮。
Tool access is not a list of buttons.
它是模型和真实世界之间的接口。
It is an interface between the model and the real world.
每个工具都需要明确的用途、可预期的输出、清晰的失败状态和权限边界。
Every tool needs a clear purpose, predictable output, explicit failure state, and a permission boundary.
好工具能在模型开始乱推理之前就消掉歧义。
Good tools reduce ambiguity before the model has a chance to reason badly.
烂工具只会逼模型去猜刚才到底发生了什么。
Bad tools force the model to guess what happened.
[ ] Is success defined before execution begins
[ ] Can the agent find the right project knowledge without loading everything
[ ] Does every tool have a clear contract and failure state
[ ] Is execution isolated from production systems
[ ] Are important decisions stored outside the conversation
[ ] Does every risky transition have evidence
[ ] Are irreversible actions protected by approval
[ ] Does every loop have a retry cap and budget
[ ] Can the run resume after interruption
[ ] Can you explain every tool call and state change
[ ] Does failure update a guide, test, tool, or policy
[ ] Can the final artifact be rolled back
4. 把记忆外化成持久状态
4. Externalize memory into durable state
对话不是系统的记账本。
The conversation is not the system of record.
把决定、产物、失败和未关的风险存在上下文窗口之外。
Store decisions, artifacts, failures, and open risks outside the context window.
下一次会话应该继承这项工作的状态，而不是一段有损的口头复述。
The next session should inherit the state of the work, not a lossy retelling of the conversation.
这也是 agent 能扛过上下文重置、崩溃和交接的原因。
This is how an agent survives context resets, crashes, and handoffs.
for (let attempt = 1; attempt <= 3; attempt += 1) {
const artifact = await build(state)
const evidence = await verify(artifact)
if (evidence.pass) return artifact
state.failures.push(evidence.gap)
state.repair = evidence.repair
}
return requestHumanReview(state)
5. 先装传感器，再谈自主性
5. Add sensors before adding autonomy
agent 没法纠正它看不见的东西。
An agent cannot correct what it cannot observe.
测试、linter、截图、日志、指标、schema 校验器，把模糊的「质量」变成证据。
Tests, linters, screenshots, logs, metrics, and schema validators turn vague quality into evidence.
LEVEL 0
prompt + model
LEVEL 1
project guide + tools
LEVEL 2
structured state + tests + bounded loop
LEVEL 3
permissions + traces + recovery + human gates
模型产出一个产物。
The model creates an artifact.
环境产出关于这个产物的证据。
The environment produces evidence about the artifact.
harness 判断这份证据够不够继续往下走。
The harness decides whether that evidence is enough to continue.
CODE -> tests + type checks + lint
UI -> render + screenshot + visual inspection
RESEARCH -> source check + contradiction check
DATA -> schema + range + freshness checks
6. 把权限放到模型外面执行
6. Enforce permissions outside the model
模型可以建议一个动作。
The model can recommend an action.
harness 必须授权这个动作。
The harness must authorize it.
当动作昂贵、不可逆、或者会碰到别人的时候，这个分离最要紧。
This separation matters most when the action is expensive, irreversible, or touches another person.
不要指望同一个概率系统既出方案、又批风险、还执行副作用。
Do not ask the same probabilistic system to invent the plan, approve the risk, and execute the side effect.
AGENTS.md
-> architecture map
-> testing map
-> product rules
-> security rules
-> task-specific guides
7. 记录 trace，并能局部恢复
7. Record traces and recover locally
每次运行都应该留下可读的痕迹。
Every run should leave a readable trail.
没有 trace，失败就成了悬案。
Without traces, failure becomes a mystery.
有了 trace，失败就变成下一轮 harness 改进的输入。
With traces, failure becomes input for the next harness improvement.
指令应该变成基础设施
Instructions should become infrastructure
大多数团队把重要规则写成散文。
Most teams keep important rules in prose.
agent 读了它。
The agent reads them.
然后终有一天忽略了其中一条。
Then eventually ignores one.
更强的做法是把重要规则编码两次。
The stronger pattern is to encode the important rule twice.
第一次是 agent 能理解的指引。
First as guidance the agent can understand.
第二次是 agent 绕不过的机械检查。
Then as a mechanical check the agent cannot bypass.
指引解释理由。
The guide explains the reason.
检查守住边界。
The check enforces the boundary.
这就把一次过去的失败变成了系统里永久的改进。
This turns a past failure into a permanent system improvement.
下一个 agent 不需要记得那次事故。
The next agent does not need to remember the incident.
harness 替它记得。
The harness remembers for it.
循环归 harness 管
The loop belongs to the harness
长任务需要迭代。
Long-running work needs iteration.
但「一直试到成功为止」不是控制系统。
But “keep trying until it works” is not a control system.
有用的循环要有证据、有重试上限、有预算、有升级路径。
A useful loop has evidence, bounded retries, a budget, and an escalation path.
模型应该决定怎么补上局部的缺口。
The model should decide how to repair the local gap.
harness 应该决定还允不允许再试一次。
The harness should decide whether another attempt is allowed.
Anthropic 在长跑 agent 的实践里得出了类似结论。
Anthropic reached a similar conclusion in its work on long-running agents.
结构化产物跨会话保住连续性，而独立的评估器给构建者具体反馈，而不是让它自己给自己评卷。
Structured artifacts preserve continuity across sessions, while a separate evaluator gives the builder concrete feedback instead of letting it approve its own work.
“找最简单的方案，只在必要时才加复杂度”
Anthropic，《Harness design for long-running application development》
“Find the simplest solution possible, and only increase complexity when needed”
Anthropic, Harness design for long-running application development
失败应该升级系统
Failure should upgrade the system
https://www.anthropic.com/engineering/harness-design-long-running-apps
大多数人修的是当前这份输出。
Most people repair the current output.
harness engineer 修的是这一类失败。
Harness engineers repair the class of failure.
MISSING CONTEXT -> add a map or retrieval rule
WRONG TOOL -> improve tool description or routing
BAD OUTPUT -> add a validator or stronger contract
REPEATED LOOP -> add a retry cap and escalation
UNSAFE ACTION -> add a permission gate
LOST DECISION -> store it in durable state
UNKNOWN FAILURE -> add tracing and evidence capture
{
"task_id": "task_042",
"current_step": "verify_ui",
"artifacts": ["build.zip", "report.md", "screenshot.png"],
"decisions": ["keep existing schema"],
"failures": ["mobile overflow at 390px"],
"pending": ["human approval"]
}
立刻打的那个补丁只修好一次运行。
The immediate patch fixes one run.
harness 上的改动改善之后每一次运行。
The harness change improves every run after it.
这就是复利优势。
That is the compounding advantage.
一个好的 harness 会把 agent 的错误转成基础设施
A good harness converts agent mistakes into infrastructure.
把大脑、手和历史分开
Separate the brain, the hands, and the history
一个可靠的 agent，在把三个部件分开之后会更容易想清楚。
A reliable agent is easier to reason about when three components are separate.
https://t.me/+qqS3Qn-x1305ZmUy
沙箱死了，历史还在。
If the sandbox dies, the history survives.
模型换了，工具和策略依然可检视。
If the model changes, the tools and policy remain inspectable.
任务恢复时，新会话可以从产物和 trace 里重建状态。
If a task resumes, a new session can reconstruct the state from artifacts and traces.
Anthropic 的 Managed Agents 架构通过 session、harness、sandbox，把这个分离明确表达了出来。
Anthropic’s Managed Agents architecture makes this separation explicit through the session, harness, and sandbox.
重要的不是哪家厂商。
The important part is not the vendor.
是这套架构。
It is the architecture.
推理引擎不该同时兼任文件系统、权限系统、记忆数据库和审计日志。
The reasoning engine should not also be the filesystem, permission system, memory database, and audit log.
request
selected context
tool calls
state changes
verification results
retries
cost
final artifact
rollback point
给每次运行留一份变更凭据
Give every run a change receipt
agent 干完活，别只留最终输出。
When the agent finishes, do not keep only the final output.
留一份紧凑的凭据，说明这份输出是怎么产出的。
Keep a compact receipt that explains how the output was produced.
这让模型升级可比较。
This makes model upgrades comparable.
让回退可归因。
It makes regressions attributable.
让审计成为可能。
It makes audits possible.
也让最终答案没法掩盖一个坏掉的过程。
And it prevents the final answer from hiding a broken process.
MODEL
reasons and proposes actions
HARNESS
selects context
exposes tools
stores state
enforces permissions
checks results
records traces
recovers from failure
从能闭环的最小 harness 开始
Start with the smallest harness that closes the loop
harness engineering 不是让你在做第一个任务之前先造一个平台。
Harness engineering does not mean building a platform before the first task.
从能观察、能验证、能恢复的最小系统开始。
Start with the smallest system that can observe, verify, and recover.
只有当任务挣来了复杂度，才往上加。
Move up only when the task earns the complexity.
一个短的、低风险的任务可能只需要一次提示加一次评审。
A short low-risk task may need one prompt and one review.
一个能改文件、能上网、能开 PR 的六小时编码任务，才需要真正的 harness。
A six-hour coding run that can edit files, access the network, and open a pull request needs a real harness.
harness 应该比它控制的失败面更小。
The harness should be smaller than the failure surface it controls.
MODEL SUGGESTS -> POLICY CHECKS -> TOOL EXECUTES
harness engineering 检查清单
The harness engineering checklist
在你把真实工作交给 agent 之前，先问：
Before you trust an agent with real work, ask.
BRAIN
the model that reasons
HANDS
the sandbox and tools that act
HISTORY
the append-only record of what happened
如果好几个答案都是「否」，那更强的模型也不会让这套系统变可靠。
If several answers are no, a stronger model will not make the system reliable.
它只会让这次失败更贵。
It will only make the failure more expensive.
真正的转变
The real shift
prompt engineering 告诉模型该做什么。
Prompt engineering tells the model what to do.
context engineering 决定模型看到什么。
Context engineering decides what the model sees.
harness engineering 造出模型在其中行动的那个世界。
Harness engineering builds the world in which the model acts.
PROMPT -> instruction
CONTEXT -> working view
HARNESS -> operating system
LOOP -> local improvement
GRAPH -> coordination
模型下个月可能就换了。
The model may change next month.
工具、测试、状态、策略和 trace 可以一直改进。
The tools, tests, state, policies, and traces can keep improving.
这就是为什么持久的优势正在从提示词里，转移到模型周围的系统里。
That is why the durable advantage is moving out of the prompt and into the system around it.
最好的构建者不会只问哪个模型最聪明。
The best builders will not only ask which model is smartest.
他们会问：哪个环境能让这份聪明变得可靠。
They will ask which environment makes that intelligence reliable.
这就是 harness engineering。
That is harness engineering.
如果你读到这里
If you read this far
-> Subscribe to my Substack.
-> Join my Telegram.
-> 把文章收藏起来，等你搭下一个 agent 时用这份清单
-> Bookmark the article so you can use the checklist when you build your next agent.
-> 关注 @0xwhrrari，看更多 agent 系统的实操拆解
-> Follow @0xwhrrari for more practical breakdowns of agent systems.