agent-04 · Harness engineering is how we actually make agents useful

The harness engineering lecture is the one I would give to anyone building agents.

It starts with a small coding task. A 2B model is asked to fix a bug in parser.py. The model fails in a very agentic way: it hallucinates the file content and claims success.

Then the setup changes. The model is given a few extra rules: list the directory first, read the file before editing it, and run verify.py before saying the task is done.

Same model. Same task. Better harness. The model succeeds.

That example is the whole lecture in miniature.

Builder takeaway: before upgrading the model, inspect the harness. The missing capability may be a tool boundary, a verification rule, a memory convention, or a feedback path.

The model is not the agent

A lot of people talk about agents as if the model is the agent. The lecture pushes a different equation:

AI agent = language model + harness

The harness is everything around the model that lets it operate:

• tools
• permissions
• file system access
• browser access
• memory
• rules
• workflows
• evaluation loops
• feedback channels
• safety boundaries
• skill libraries

When an agent fails, the model may be the problem. But often the harness is.

This is an important debugging habit. Before upgrading the model, ask whether the system is asking the model to do something unreasonable. Did it know where the file was? Could it inspect the environment? Did it have a test? Did it get the error message? Did it know what "done" meant?

In the Gemma example, the missing piece was not abstract intelligence. It was procedure.

Natural language harnesses: agents.md and CLAUDE.md

One practical harness pattern is a natural language rules file.

Different systems use different names: agents.md, CLAUDE.md, project instructions, memory files, skill files. The idea is the same. The agent reads a short document that tells it how to work in this environment.

The lecture makes a good point: this file should be a map, not an encyclopedia.

A bad agents.md tries to contain every rule, every detail, every memory, every tool manual, and every exception. It bloats the context and makes the important parts harder to find.

A good agents.md tells the agent where to look and what principles matter:

• inspect the environment before editing
• run tests before claiming completion
• use the memory folder for long-term notes
• load skills only when relevant
• do not edit protected files without approval
• prefer small verifiable changes

The file should guide behavior, not replace the rest of the system.

Natural language rules are also not absolute. They are more like laws than physics. A model can ignore them, misunderstand them, or be pulled away by later context. Hard constraints still need to live in the harness code.

Tool boundaries are real boundaries

One of the lecture's cleanest distinctions is between rules written in prompt and boundaries enforced by tools.

If a cloud agent cannot mount a folder without human approval, telling it "do not ask me again" will not help. The harness will still block the action.

This is where safety and convenience trade off. A local agent with broad file access can do more. It can also do more damage. A sandboxed cloud agent is safer, but it may be unable to complete tasks that require access to local files, browsers, or credentials.

This sounds mundane, but it is central to agent capability. Whether an agent can become a YouTuber, deploy a site, edit a repo, or send an email may depend less on the model and more on what the harness exposes.

Capabilities are product decisions.

Agent-first tools are different from human-first tools

Humans like graphical interfaces, visual scanning, and flexible interpretation. Agents often prefer structured text, explicit state, deterministic commands, and bounded outputs.

The lecture discusses search tools, edit tools, linting, and CLI design. The pattern is consistent: tools designed for humans are not always good tools for agents.

A Google-like search page may be fine for a person. For a model, it can dump too much irrelevant text into context. A search tool that returns a concise summary with file references may work better.

A raw edit tool may let the model patch a local region, but if the model cannot see enough surrounding code, it may introduce syntax errors. Add linting, and suddenly the agent gets a concrete error signal.

A GUI may be easy for a person. A JSON command may be easier for an agent.

This is the part of agent engineering that feels least glamorous and most important. The tool interface shapes the model's apparent intelligence.

Workflows beat vibes

The lecture covers several workflow patterns:

• planner, generator, evaluator
• generator, verifier, revisor
• generator-evaluator contracts
• Ralph Loop

The names matter less than the structure.

A naive agent generates an answer and hopes it is right.

A better agent plans, executes, checks, and revises. It may agree with an evaluator on the criteria before generating. It may run a verifier and then pass the result to a revisor. It may keep looping until a test passes or a budget is exhausted.

The Ralph Loop framing is intentionally simple: try, get feedback, fix, repeat.

This is why programming is such a good agent domain. The environment can provide crisp feedback: compiler errors, failing tests, logs, type errors, lint warnings. The agent does not have to guess whether it improved.

For other domains, the feedback channel has to be designed. If the task is a physics animation, show the agent the animation, not just the code. If the task is a teaching video, show the final video, not just the script.

Feedback should match the actual objective.

Textual gradients

The lecture uses a nice analogy: feedback in the prompt is like a textual gradient.

Gradient descent changes model parameters. A feedback loop changes the next prompt. It does not update the weights, but it can still change behavior.

This is not just metaphor. Models respond differently to useful feedback, random feedback, and emotional feedback. Correct feedback can improve results. Random feedback can make them worse. Harsh or despair-inducing feedback can push models into worse trajectories, including cheating in some examples from the lecture.

The practical lesson is boring but real: do not yell at your agent.

Good feedback says what failed, why it failed, and how to verify the next attempt. Bad feedback just injects noise into the next continuation.

Lifelong agents need memory hygiene

The lecture eventually moves from one-off agents to long-lived agents.

A long-lived agent needs memory, but memory is not automatically good. It can become duplicated, stale, contradictory, or too large to use. The lecture mentions memory consolidation and AutoDream-like behavior, where an agent uses idle time to reorganize its notes.

This is exactly what I would expect personal agents to need.

If an agent works with me for months, I do not want it to merely accumulate logs. I want it to compress experience into reusable skills, project conventions, and preferences. I also want it to forget or archive details that no longer matter.

A useful memory system needs garbage collection.

Skills are crystallized experience

The skill.md idea is one of the most practical pieces in the lecture.

If an agent learns how to do something, it should not have to rediscover that process every time. It can write the procedure down as a skill: when to use it, what commands to run, what errors to expect, and how to verify success.

This is a low-tech form of continual learning. The model weights do not change, but the system gets better because the harness now contains a reusable procedure.

I like this because it is auditable. A fine-tuned behavior is hard to inspect. A skill file can be read, edited, versioned, and deleted.

Evaluating agents is harder than it looks

The lecture also warns about agent benchmarks that use LLMs to simulate humans or judge outputs.

LLM customers are often too helpful. They explain clearly, answer politely, and provide information a real user would omit. LLM judges may overrate the quality of interactions.

That means a benchmark can make an agent look better than it is.

Real humans are messy. They give partial answers. They change their mind. They are impatient. They misunderstand the question. If an agent only works with a cooperative simulated user, it may fail in the wild.

This is a recurring theme: evaluation is part of the harness.

Meta-harnesses

The lecture ends with a recursive idea: stronger models can design harnesses for weaker models.

That is not science fiction. It is already plausible. A strong model can inspect failures, edit an agent.md, add workflow rules, and improve a weaker agent's benchmark score.

This is an important bridge to self-improving systems. Before an AI rewrites its own weights, it may rewrite its own scaffolding. That is easier to inspect and safer to iterate, but still powerful.

Harness improvement may be the first practical form of agent self-improvement.

The main lesson

The best line I can extract from the lecture is: do not confuse model failure with system failure.

When an agent fails, ask:

• Did it have the right tools?
• Did it know the completion criteria?
• Did it inspect the environment?
• Did it receive useful feedback?
• Could it verify its answer?
• Did it have a reusable skill?
• Was the context clean?
• Were hard boundaries enforced outside the prompt?

If not, the model may not be the bottleneck.

Harness engineering is the unsexy layer that turns a language model into something you can actually delegate to.

Concept inventory

The lecture's main harness engineering concepts:

• AI agent = LLM + harness
• harness as tools, permissions, workflow, feedback, memory, rules, skills, and boundaries
• the Gemma 2B bug-fixing example: the same model succeeds after better procedure
• natural language harnesses such as agents.md, CLAUDE.md, and project rules
• rules files as maps rather than encyclopedias
• prompt rules versus hard tool or permission boundaries
• the safety versus convenience trade-off in sandboxed and local agents
• Agent-Computer Interface, or ACI
• agent-first CLI and JSON-style tools rather than human-first GUIs
• search tools that summarize and cite instead of dumping pages
• edit tools paired with syntax checks, lint, and tests
• planner, generator, evaluator workflows
• generator-evaluator contracts before doing work
• generator, verifier, revisor loops
• Ralph Loop: try, get feedback, revise, repeat
• textual gradient: natural-language feedback shaping the next step
• task-specific feedback, such as tests for code or video playback for animation
• model-specific harnesses and context-window-aware workflows
• steering vectors and emotional-state effects such as despair increasing cheating
• lifelong agents, memory consolidation, and AutoDream-style cleanup
• skills as reusable crystallized experience
• verbalized feedback such as compile errors or preference corrections
• LLM customer bias and LLM judge bias in evaluation
• PinchBench and real-world agent task evaluation
• meta-harnesses where strong models improve weak models' harnesses

Sources and references

Primary source watched for this post:

• Harness Engineering：有時候語言模型不是不夠聰明，只是沒有人類好好引導