What is an agent harness? The layer that makes an AI model useful

1. 1

   What is an agent harness, in one sentence?

   A model on its own can only read text and write text. To fix a bug, fill a spreadsheet or book a meeting, something has to hand it tools, feed it the right files, run its commands and pass the results back. That something is the harness.

   Anthropic’s Claude Code docs put it plainly: Claude Code is the layer around the model that provides the tools and manages the context the model sees, and that surrounding layer is what "agentic harness" means. The same Claude model sits inside the chat app, Claude Code and many other products. What differs is the harness.

   1. Your task↓→
   2. Harness picks context and tools↓→
   3. Model decides a step↓→
   4. Harness runs it↓→
   5. Result goes back to the model

   Key idea

   Agent = model + harness. The model reasons; the harness gives it hands, memory and a checker.

2. 2

   What does a harness do on every task? (the loop)

   Anthropic describes the work of an agent as a loop with three phases: gather context, take action, verify the result, then repeat until the task is done. Each phase has harness parts behind it.

   Gathering context uses search over your files, subagents and compaction (summarising old conversation so the context window does not overflow). Taking action uses tools, shell commands and MCP servers. Verifying uses fixed rules such as a linter, screenshots, or a second model acting as a judge.

   1. Gather context↓→
   2. Take action↓→
   3. Verify the result↓→
   4. Repeat or finish

   Key idea

   When an agent fails, ask which phase failed: did it lack context, lack a tool, or lack a way to check its work?

3. 3

   Which parts of a harness can you change yourself?

   You do not need to build a harness to improve one. Modern harnesses expose a handful of parts you can edit. The table shows the ones in Claude Code, with what each does and what it costs in context. Cursor and Codex have close equivalents: an AGENTS.md or rules file, skills, MCP servers and approval settings.

   A connector is the friendly name for the MCP part. When you switch on Gmail, Google Drive or Slack in a chat app, you are adding an MCP server to the harness, so the model can read and act in that app.

   Claude Code docs · Nov 2026

   Six harness parts you control, and what each one costs in context

   Part	What it does	When it loads	Add it when
   Instruction file (CLAUDE.md, AGENTS.md)	Standing rules the agent sees every session	Session start, in full, on every request	Same rule broken twice
   Skill	A saved how-to for one kind of task	Description at start; full text only when used	Third paste of a procedure
   MCP server (connector)	Access to an outside app or database	Tool names at start; full details on demand	You keep pasting app data
   Subagent	A helper with its own separate context	Only when spawned; returns a summary	Side task floods the chat
   Hook	A script that runs at a set moment, every time	Runs outside the conversation; no context cost	Must run every time
   Permissions	What the agent may do without asking you	Always in force	Trust or block a command

   Key idea

   Every part you add uses some context or adds a rule. Add a part only when a real, repeated problem calls for it.

4. 4

   Does the harness really change the result? Two Anthropic experiments

   In November 2025, Anthropic engineers asked a strong model to build a clone of the claude.ai web app from one high-level prompt. Run in a plain loop, it failed in two ways: it tried to do too much at once and ran out of context mid-feature, and later sessions looked at the half-built app and declared it finished. The fix was not a new model. It was harness work: a first session that wrote a list of over 200 features, each marked as failing, a progress file, a script to start the app, and a rule that each later session finishes one feature, tests it in a browser like a user, and commits.

   In March 2026, Prithvi Rajasekaran of Anthropic compared the same model alone and inside a three-agent harness (a planner, a generator and a separate evaluator that clicks through the app). The task was a retro game maker.

   Anthropic Engineering · retro game maker · Opus 4.5

   Same model, same prompt: the harness run cost over 20 times more and produced a game that worked

   Measure	Model alone	Planner + generator + evaluator
   Time	20 minutes	6 hours
   Cost	$9	$200
   Plan it worked from	The short prompt	A 16-feature spec built over ten sprints
   Result	Core game mechanics were broken	The game was playable

   Key idea

   A separate checker matters because, in the author’s words, "agents reliably skew positive when grading their own work".

5. 5

   Worked workflow: set up a small harness for a weekly task

   Here is the same thinking applied to a job seeker’s weekly routine: tailoring a resume to five job posts. The example is ours; the order of steps follows the triggers in the Claude Code docs. You can do it in Claude Code, Cursor or Codex, and the first two steps work in any chat app with projects and connectors.

   Worked workflow

   Worked workflow: five tailored resumes, checked, every week

   Input

   A folder with master-resume.md, five saved job posts, and an agent tool such as Claude Code.

   1. 1

      Write the standing rules (instruction file)

      Put the rules that never change in CLAUDE.md or AGENTS.md at the top of the folder. Keep it short; the docs suggest under 200 lines.

      Copy

      # Rules
      - Never invent a number, employer or tool. Write [add a number] instead.
      - One page. Keep my section order.
      - Save each result as out/<company>-resume.md. Never edit master-resume.md.

   2. 2

      Save the procedure once (skill)

      Create a tailor-resume skill: read the post, list its ten most important requirements, map each to a line in the master resume, rewrite only those lines, and list the requirements you could not match.

   3. 3

      Connect the source (MCP connector)

      If the job posts live in Google Drive or Notion, add that connector so the agent reads them directly instead of you pasting them in.

   4. 4

      Enforce the one rule that must never break (hook or permission)

      A rule in a file is only a request. Deny edits to master-resume.md in permissions, or add a hook that blocks any edit to that file.

   5. 5

      Give it a way to check its work (verification)

      Borrow Anthropic’s feature-list idea: a checklist file with one line per post, each marked "fails" until the agent has confirmed one page, no invented facts and the unmatched-requirements list. The agent may only flip a line to "passes".

      Copy

      [
        { "post": "acme-analyst", "one_page": false, "no_invented_facts": false, "gaps_listed": false, "passes": false }
      ]

   Output

   Five files in out/, a checklist showing which passed, and a list of real gaps per job. Next week you drop in five new posts and type one line.

   Key idea

   You improved the result without touching the model or writing a cleverer prompt. That is harness work.

6. 6

   What is harness engineering, and how much harness is enough?

   In February 2026, OpenAI’s Ryan Lopopolo described a team that shipped an internal product with no hand-written code: roughly one million lines and about 1,500 merged pull requests in around five months, started by three engineers. Their job changed from writing code to building the harness: a short AGENTS.md of about 100 lines that points to deeper docs, linters whose error messages tell the agent how to fix the problem, and background agents that clean up drift. Their rule for context: "give Codex a map, not a 1,000-page instruction manual".

   More harness is not always better. Rajasekaran’s March 2026 post notes that "every component in a harness encodes an assumption about what the model can’t do on its own", and those assumptions go stale. When a newer model could work for over two hours without losing the thread, his team removed the sprint structure and kept only the planner and the evaluator.

   • Start with the simplest setup: an instruction file and good permissions.
   • Add one part when the same failure shows up twice.
   • After a model upgrade, remove parts and see if anything gets worse.
   • Keep everything the agent needs inside the project. OpenAI’s team: "What Codex can’t see doesn’t exist."

From the people who built it

Straight from the source

The original idea, then the same idea taken apart, then how you use it today.

Prithvi Rajasekaran

Anthropic Labs engineer who built and measured multi-agent harnesses for long coding tasks

Harness design for long-running application development (Anthropic Engineering, March 2026)

1 · Understand

Separate the agent that builds from the agent that judges, and treat every harness part as an assumption about a model weakness that may no longer be true.

2 · Break it down

• A planner turns a one-line request into a spec, so the builder is not guessing the scope.
• A separate evaluator uses the running app like a user; it is easier to make a judge strict than to make a builder self-critical.
• The harness run took 6 hours and $200 against 20 minutes and $9 alone, and only the harness run produced a working game.
• With a newer model, the team removed the sprint structure (context resets had already gone) because the model no longer needed it.

3 · Use it

Give your agent a written definition of "done" and a separate check. After each model upgrade, try removing one part of your setup.

Ryan Lopopolo

OpenAI engineer on a team that shipped a product written entirely by Codex

Harness engineering: leveraging Codex in an agent-first world (OpenAI, February 2026)

1 · Understand

When agents write the code, the engineer’s job is to design the environment: "Humans steer. Agents execute."

2 · Break it down

• One huge instruction file crowded out context and went stale; a short AGENTS.md of about 100 lines pointing to deeper docs worked better.
• Anything outside the project folder (chat threads, documents, what is in your head) does not exist for the agent.
• Rules were enforced by linters and tests whose error messages tell the agent how to fix the problem.
• When an agent failed, the fix was usually a missing tool or missing structure, not asking it to try harder.

3 · Use it

Keep your instruction file short and use it as a table of contents. When the agent fails, ask what it could not see or could not do, and add that.

6 terms

Words to know

Agent harness

The software around a model that gives it tools, manages what it sees, keeps state and checks its work. Also called an agentic harness or scaffold.

Agentic loop

The cycle an agent repeats: gather context, take action, verify the result.

Compaction

Summarising or clearing older conversation so the context window does not overflow during long work.

Hook

A script the harness runs at a fixed moment, such as before a tool is used. It runs every time, whatever the model decides.

Connector

A ready-made link between an AI app and another service such as Gmail or Slack, usually built on MCP.

Harness engineering

Improving an agent by changing its environment, instructions, tools and feedback loops rather than the model.

2 videos · plays here

Watch

Hand-picked from the people who explain this best. The video loads only when you press play.

Hands-on · 10 minutes or less

Try it

Find the weak part of your own harness

1. 1Pick one task you give an AI tool every week and where the result often needs fixing.
2. 2Write down the last two failures. For each, mark the phase: missing context, missing tool or access, or no check.
3. 3Missing context twice? Add a short instruction file or project instructions with the rule it broke.
4. 4Missing access? Switch on one connector (Drive, Gmail, Notion) so you stop pasting.
5. 5No check? Add a five-line checklist the agent must fill before it says "done", then run the task again and compare.

Claude Code docs: when to add each part

Practise this lesson with an AI tutor

It checks what you understood, then gives you a small real task to try.

Open in Claude Open in ChatGPT Copy prompt

Read the prompt

Be my patient tutor. I just studied this lesson: "What is an agent harness?". Summary: An agent harness is the software wrapped around an AI model: it gives the model tools, decides what the model sees, keeps notes between sessions, and checks the work. The model does the thinking; the harness does everything else. Claude Code, Cursor and OpenAI Codex are harnesses, and the parts you can change yourself are instruction files, skills, MCP connectors, subagents, hooks and permissions.
Key terms: Agent harness, Agentic loop, Compaction, Hook, Connector, Harness engineering.

Do this, one step at a time, waiting for me each time:
1. Ask me to explain the main idea in my own words. Correct me kindly with one concrete example.
2. Ask 4 questions, easy to hard. After each answer, say what was right and what was missing.
3. Give me one small workflow I can try in 10 minutes that uses this idea in real work or study. Walk me through it step by step and check my result.
4. End with 3 lines: what I now know, what I should practise, what to learn next.

3 questions · instant feedback

Check yourself

Pick an answer to see if you are right, and why.

Question 1

Question 1 of 3

Which of these is part of the harness, not the model?

AThe weights learned in trainingBThe code that runs a shell command and returns its output to the modelCThe model’s ability to reason about codeDThe number of parameters

Question 2

Question 2 of 3

Your agent keeps editing a file it must never touch, even though the instruction file says not to. What is the right fix?

AWrite the rule again in capital lettersBSwitch to a bigger modelCAdd a hook or permission rule that blocks the editDAdd a skill describing the rule

Question 3

Question 3 of 3

After a model upgrade, what does Anthropic’s March 2026 post suggest doing with your harness?

AAdd more agents to use the extra capabilityBLeave it exactly as it isCRemove parts that are no longer needed and keep the simplest setup that worksDRewrite every prompt

Lesson 28 of 42

Done? Keep going

Mark this lesson complete to keep your place. Progress is saved on this device, no login.

Mark lesson complete

Up next · Lesson 29 · 12 minPrompt injection and AI securityPrompt injection is when text an AI reads, typed by a user or hidden in an email, web page or file, overrides the instructions it was given. It works because a language model cannot reliably tell your instructions apart from the data it is processing. It matters most for AI agents that can read private data and take actions, and the best defence today is limiting what an agent can do, not asking it to be careful.

Roles that need this lesson · 3

• AI Engineer interview guideInterviewers ask why an agent failed. Naming the harness part (context, tool, check) is the strong answer.Open the guide
• Forward Deployed Engineer interview guideMost customer agent work is harness work: connectors, permissions and checks around a model you cannot change.Open the guide
• AI Product Manager interview guideKnowing what belongs to the model and what belongs to the harness is how you scope an agent feature.Open the guide

← Previous: Subagents and multi-agent systems

People also ask

Questions people ask

What is the difference between an AI model and an agent harness?+

The model is the trained network that reads text and predicts what comes next. The harness is the software around it that supplies tools, chooses what the model sees, stores notes and checks results. An agent is the two working together.

Is Claude Code a harness? What about Cursor and Codex?+

Yes. Anthropic’s docs describe Claude Code as the layer around the model that provides tools and manages context, which is what an agentic harness is. Cursor and OpenAI Codex play the same role around the models they run.

Is MCP part of the harness?+

MCP is the standard a harness uses to connect to outside apps and data. Each MCP server or connector you add becomes one more set of tools the harness can offer the model.

6 sources · checked Nov 2026

Sources and further reading

• Claude Code docs: How Claude Code works (the agentic loop and harness)
• Claude Code docs: Extend Claude Code (CLAUDE.md, skills, MCP, subagents, hooks)
• Anthropic Engineering: Effective harnesses for long-running agents (26 Nov 2025)
• Anthropic Engineering: Harness design for long-running application development (24 Mar 2026)
• Anthropic: Building agents with the Claude Agent SDK (29 Sep 2025)
• OpenAI: Harness engineering: leveraging Codex in an agent-first world (11 Feb 2026)

Related on this site

Previous: Subagents and multi-agent systemsNext: Prompt injection and AI securityWhat is MCP?Connectors: Gmail, Drive and Slack in AIWhat are Agent Skills?Context engineeringThe levers that make answers betterClaude Code for beginnersAI engineer career guide