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.

Every step as text

“Hi, how are you?”

  1. 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.

  2. 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?

  3. 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?

  4. 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?”

  1. You type and press Enter

    The harness receives the question. The answer is in a project file, not in the model.

  2. 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?

  3. 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")

  4. 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.

  5. 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"

  6. 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.

  7. 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”

  1. You type and press Enter

    This time it is a task, not a question. It will take reading code, editing it and checking it.

  2. 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

  3. 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")

  4. The harness reads the files

    Reading project files is allowed, so the harness runs both reads.

  5. 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() … }

  6. 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")

  7. The harness edits and a hook formats

    Editing project files is allowed. Right after, the after-edit hook formats the file with Prettier.

  8. 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

  9. 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.

  10. 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)

  11. 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")

  12. The harness edits and formats again

    The same permission rules and the same format hook as in the previous round.

  13. 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

  14. 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.

  15. 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.

  1. Section 01

    Foundations

    How to frame a task and what information the agent needs, now and across sessions.

    1. Start here
      Base setup

      The starting point: an agent with no additional configuration.

    2. On the path
      Task 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.

    3. On the path
      Context 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.

    4. On the path
      State 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.

  2. Section 02

    Project context

    Persistent instructions and reusable procedures to guide the work.

    1. On the path
      AGENTS.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.

    2. On the path
      Skills: 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.

  3. Section 03

    External capabilities

    Tools, external servers and the boundaries that contain what the agent can do.

    1. On the path
      Tools 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.

    2. On the path
      Model 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.

    3. On the path
      Safe 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.

  4. Section 04

    Control and coordination

    Check the result, automate the checks and split the work without losing control.

    1. On the path
      Verification 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.

    2. On the path
      Hooks: 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.

    3. On the path
      Subagents 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.