Anatomy of a coding agent harness

A coding agent's harness is everything around the model that shapes what an agent does: the agent program, its instructions, skills, hooks, tools and checks. In detail, that means the files that tell it what to do, the procedures it can load, the scripts that run before its actions, the helpers it can launch, the tools it can call and the records it keeps. AR Labs builds on Claude Code, an AI coding agent (an AI agent that writes code), and we treat each of these as a separate part with its own job. Knowing which part a piece of guidance belongs in is most of the skill: put it in the wrong one and it is either ignored, or loaded into every session where it crowds out what matters.

The problem it answers

The easiest place to put any instruction is the always-loaded instruction file, and that is where most guidance ends up by default. The file grows, and every session pays for all of it before any work starts. Matt Pocock's advice in his public workshop on AI coding is to keep the standing prompt as small as possible for exactly this reason. Meanwhile rules that matter most are still only text, which an agent under pressure can skip. The answer is to give each kind of guidance the part of the harness built for it.

The parts

The figure puts the model's context window at the centre. Instructions and rules on the left are pushed into it every session; skills, commands and records on the right are pulled in when relevant. Every tool call the model makes passes through the hooks before it reaches a tool, and the floor scripts at the bottom left check the world without any model involved.

Part	What it is	What it is for	Loaded
Instructions	AGENTS.md or CLAUDE.md at a repository or folder root	What success looks like, and where to read next	Always (pushed)
Rules	Short files of standing constraints, optionally matched to paths or file types	Constraints for every session, or only when touching certain files	Always, or when matching files are touched
Skills	A folder with a SKILL.md and supporting files	Specialised know-how: how to draw a C4 diagram, how to run an interview	When the task calls for it (pulled)
Commands	Written procedures for a named step	The exact method for one pipeline step, executed by reference	When the step runs
Hooks	Scripts the runtime calls at events	Enforcing what must not depend on the agent remembering	On every matching event
Subagents	Defined helpers with their own context, model and tool list	Isolating research, review or extraction from the main context	When delegated to
Tools and MCP servers	Capabilities the agent can call, described by schemas	Acting on the world: search, diagram validation, issue tracking	Listed always, called on demand
Memory and records	Notes, the issue tracker, session history	State that must outlive the session	Read when needed

Push versus pull. Pushed context occupies the window from the first token of every session. Pulled context enters only when it is relevant. The design question for each piece of guidance is how often it matters across all the turns an agent might take. Identity and the map of where things live are pushed; how to write a C4 diagram is pulled.

Instructions route; they do not restate. Our top-level instruction files are short maps: what this place is for, and which document to read for each concern. Each fact lives in the one document that loads when it is relevant (see progressive disclosure).

Commands are executed, not remembered. A pipeline step's procedure lives in a command file, and agents are required to open and follow it rather than work from a remembered version. We found that procedures reconstructed from memory silently lose steps.

Hooks enforce. Hooks in our harness fall into three groups. Context hooks load the session's starting context and note when the conversation is about to be compacted. Guard hooks run before a tool call and can deny it with a reason: refusing edits to a project's main checkout, refusing pipeline state changes that skip a step, refusing an unattended session's edits to the pipeline's own machinery. Observation hooks capture events for later analysis, and a health probe reports when the issue tracker is unreadable instead of reporting zero issues. The guards are themselves covered by a test suite. See harness engineering.

Subagents are context forks with a declared model. Each definition pins a model and a tool list. Read-only work gets agents without edit tools, which avoids both accidental changes and permission prompts that would stall a background agent. Research agents have no tool for launching further agents, so a fan-out cannot recurse.

Tools have contracts. An agent knows a tool only from its schema, so we write schemas as instructions: strict types, enumerations, examples. MCP servers bring in external capabilities the same way; our diagram workflow, for example, validates and exports C4 diagrams through Structurizr's MCP server.

Durable records, not conversation. Anything that must survive the session goes to a file or the issue tracker. The coding pipeline keeps its entire state as metadata on tasks, written by one script, so a new session resumes from the record without a handoff.

Runtime, model and role

We keep three things separate. The runtime is the agent program that runs a step, such as Claude Code or Codex; it is one part of the harness. The model is what the runtime talks to. The role is the job in the pipeline: spec author, implementer, reviewer. They vary independently: the reviewer role already runs on a different runtime and vendor from the implementer, and the spec author can be chosen per task. Anthropic's engineering post on Managed Agents makes a related cut, separating the session (an append-only log of what happened), the harness (in Anthropic's narrower sense, the loop that calls the model and routes its tool calls) and the sandbox (where code runs), so that each can be replaced without disturbing the others. Our design for VOX OS, an operating layer over agent work, follows the same direction.

A worked example: one rule, three parts

Rule: never edit a project's main checkout; work in a worktree on a task branch.

• A rule file explains the rule and why it exists, so an agent understands it.
• The command file for the implementation step tells a dispatched agent that it has already been placed in the task's own worktree, on the task's branch, and must never cut a new one.
• A guard hook denies any edit whose target is inside a protected main checkout, and its denial message names the correct worktree path.

The prose explains; the command puts the rule where the step runs; the hook guarantees it. An agent that misses the first two still cannot make the edit.

What exists today

We run this structure across our repositories. An early version of the tooling for our coding pipeline is published as Coding Planner. The vendor-neutral runtime work, which lets more roles run under harnesses other than Claude Code, is in progress.