AI agent harness engineering
An agent’s environment matters too.
My working thesis: as models get better at writing code, the harness around them may become just as important. I explore that idea through practical guides.
How a harness works
One message, several rounds.
When you write to a coding agent, your message enters a loop. The harness builds the context, the model decides whether to answer or ask for a tool, and the harness runs the tool and hands back the result. Round after round, until the model answers without asking for anything else.
Claude Code, for example, calls it the agentic loop, and calls the layer that provides the tools and manages what the model sees the agentic harness. Pick a message and press Send. The examples take place in the series’ layered harness, with its permissions and hooks.
Press Send to start
You will see each step of the loop: who acts, what the model decides and what goes into the context.
What the model receives
The harness sends all of this on every call. New items go at the end.
Empty until you send a message.
- System instructions: how to work and use the tools
- AGENTS.md from the layered harness
- Tools: read_file, edit_file, run_command…
- Skills: add-endpoint and clean-code-review, name and description only
- Hi, how are you?
- Hi! I’m well, thanks. How can I help with the project?
- System instructions: how to work and use the tools
- AGENTS.md from the layered harness
- Tools: read_file, edit_file, run_command…
- Skills: add-endpoint and clean-code-review, name and description only
- Which version of Express does the project use?
- read_file("package.json")
- "express": "5.3.0"
- The project uses Express 5.3.0.
- System instructions: how to work and use the tools
- AGENTS.md from the layered harness
- Tools: read_file, edit_file, run_command…
- Skills: add-endpoint and clean-code-review, name and description only
- Add the endpoint GET /members/:id/loans
- read_file(".agents/skills/add-endpoint/SKILL.md")
- read_file("src/services/loan-service.ts")
- SKILL.md: repository → service → controller → test
- loan-service.ts: class LoanService { list() lend() … }
- edit_file("src/controllers/members-controller.ts")
- members-controller.ts: edited and formatted
- Done: I added GET /members/:id/loans.
- check-architecture-before-stop: controllers-do-not-import-repositories (code 2)
- edit_file("src/services/loan-service.ts")
- edit_file("src/controllers/members-controller.ts")
- 2 files edited and formatted
- Done: the controller calls the loan service.
Every step as text
“Hi, how are you?”
You type and press Enter
Your message does not go straight to the model. The harness receives it: the program around the model that gives it tools and decides what it sees.
The harness builds the context
It gathers the system instructions, the project’s AGENTS.md, the list of tools, the available skills and your message. The model only knows what goes in here.
Goes into the context: System instructions: how to work and use the tools · AGENTS.md from the layered harness · Tools: read_file, edit_file, run_command… · Skills: add-endpoint and clean-code-review, name and description only · Hi, how are you?
The model reads and decides
With the whole context, the model chooses between two paths: answer with text or ask for a tool. A greeting needs no tool, so it answers.
Goes into the context: Hi! I’m well, thanks. How can I help with the project?
Answer: the loop ends
The model asked for no tools, so the loop ends after a single call. The stop hooks still run, even for a greeting; the code did not change, so they pass and you see the answer.
“Which version of Express does the project use?”
You type and press Enter
The harness receives the question. The answer is in a project file, not in the model.
The harness builds the context
The same pieces as for any message: instructions, AGENTS.md, tools, skills and your question. package.json is not there yet: nobody has read it.
Goes into the context: System instructions: how to work and use the tools · AGENTS.md from the layered harness · Tools: read_file, edit_file, run_command… · Skills: add-endpoint and clean-code-review, name and description only · Which version of Express does the project use?
The model asks for a tool
The version is not in the context, so the model does not answer: it returns a structured request to read package.json. The model runs nothing on its own.
Goes into the context: read_file("package.json")
The harness checks permissions and runs it
Before running anything, the harness checks its rules: reading package.json is allowed; reading .env is not. Then it reads the file itself.
The result goes back into the context
The file contents are added to the context, right after the model’s request. The next round starts from there.
Goes into the context: "express": "5.3.0"
Second model call
The harness sends the whole context again, now with the result. The model has what it needs and answers with text, asking for no more tools.
Goes into the context: The project uses Express 5.3.0.
Answer: the loop ends
The stop hooks pass and you see the answer. A single question took two model calls and one tool.
“Add the endpoint GET /members/:id/loans”
You type and press Enter
This time it is a task, not a question. It will take reading code, editing it and checking it.
The harness builds the context
Only the name and description of the add-endpoint skill go in. Its full text loads when it is needed.
Goes into the context: System instructions: how to work and use the tools · AGENTS.md from the layered harness · Tools: read_file, edit_file, run_command… · Skills: add-endpoint and clean-code-review, name and description only · Add the endpoint GET /members/:id/loans
The model asks to read
It asks for two tools at once: read the skill and the loan service, to follow the project’s steps.
Goes into the context: read_file(".agents/skills/add-endpoint/SKILL.md") · read_file("src/services/loan-service.ts")
The harness reads the files
Reading project files is allowed, so the harness runs both reads.
The files enter the context
The skill and the service are added to the context. Every result takes up space: that is why the context grows with each round.
Goes into the context: SKILL.md: repository → service → controller → test · loan-service.ts: class LoanService { list() lend() … }
The model asks to edit
It asks to change the members controller. In this example it gets it wrong: the controller imports the loan repository and skips the service layer.
Goes into the context: edit_file("src/controllers/members-controller.ts")
The harness edits and a hook formats
Editing project files is allowed. Right after, the after-edit hook formats the file with Prettier.
The result goes back into the context
The harness adds the result of the edit. Nothing has checked the layer rule yet.
Goes into the context: members-controller.ts: edited and formatted
The model thinks it is done
It answers with text and asks for no tools. Without hooks, the loop would end here, with the rule broken.
Goes into the context: Done: I added GET /members/:id/loans.
A hook does not let it finish
The architecture hook runs dependency-cruiser, finds the forbidden import and exits with code 2. The harness does not show you the answer: it adds the error to the context and the loop goes on.
Goes into the context: check-architecture-before-stop: controllers-do-not-import-repositories (code 2)
The model fixes it
With the error in the context, it asks to add the query to the loan service and to make the controller call the service.
Goes into the context: edit_file("src/services/loan-service.ts") · edit_file("src/controllers/members-controller.ts")
The harness edits and formats again
The same permission rules and the same format hook as in the previous round.
The result goes back into the context
The harness adds the result of both edits. The context now holds everything that happened since your message.
Goes into the context: 2 files edited and formatted
The model tries to finish again
It answers with text again and asks for no tools.
Goes into the context: Done: the controller calls the loan service.
The hooks pass and it ends
This time the stop hooks pass: architecture, secrets, quality and duplicates, which only warns. You see the answer after five model calls.
Simplified example: the messages, files and results are illustrative, not a recording of a real session. The tool names are generic; each agent uses its own.
Sources, checked on 2026-10-22: How Claude Code works (Claude Code documentation); How tool use works (Claude API documentation).
Learning path
Explore the topics, step by step
Open a group to see its topics. Follow the suggested order or choose what you need now.
Section 01
Foundations
How to frame a task and what information the agent needs, now and across sessions.
- On the pathTask framing for agents
How to turn an idea into a request the agent can carry out and you can review: goal, context, boundaries, expected result, and how to know it is done.
- On the pathContext engineering for agents
What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.
- On the pathState and memory
How to make a long task survive the end of a session: keep progress outside the model, in files and in Git, and tell task state apart from long-term memory.
Section 02
Project context
Persistent instructions and reusable procedures to guide the work.
- On the pathAGENTS.md: persistent project instructions
A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.
- On the pathSkills: reusable procedures for agents
A folder with instructions, and optionally scripts and references, that teaches the agent one specific kind of task. It is only loaded when needed.
Section 03
External capabilities
Tools, external servers and the boundaries that contain what the agent can do.
- On the pathTools and permissions
What a tool is, how an agent uses one, and how to decide what it can do without asking, what needs your approval, and what is off limits.
- On the pathModel Context Protocol (MCP)
An open protocol for connecting agents to external services —databases, GitHub, task trackers— without building a separate integration for each one. It adds capabilities, and also risk.
- On the pathSafe agent execution
Why written rules are not enough to contain an agent, and which layers of the environment limit the damage even when the agent makes a mistake or someone tricks it.
Section 04
Control and coordination
Check the result, automate the checks and split the work without losing control.
- On the pathVerification and evaluation
How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.
- On the pathHooks: checks that run on their own
Commands that run automatically at specific moments of the agent’s work, such as before editing a file or when it finishes, so the important steps do not depend on the agent remembering them.
- On the pathSubagents and delegation
When it makes sense to split a task among several agents with their own context, how to give them clear assignments, and how to bring their results together without losing control.