Building Claude Code with Harness Engineering

A technical breakdown by Fareed Khan examining why modern AI coding assistants like Anthropic’s Claude Code perform reliably on complex tasks. The central thesis: superior agentic performance is driven not by prompt tuning or raw LLM benchmarks, but by harness engineering — the deterministic control loops, state management, permission layers, and tool execution environments wrapped around the model.

Source: Building Claude Code with Harness Engineering — by Fareed Khan, Level Up Coding, 2026-04-06.

Companion code: FareedKhan-dev/claude-code-from-scratch — the 23 components built up in working Python. The article and the repo are one piece of work; reading the prose without the code gets you the requirements and not the implementation.

Know the scale before you cite it. The article runs about 20,000 words across six phases and 23 components, each one built up in working Python. This note covers roughly the first third of it — the architecture — reorganised into five layers for teaching. The reorganisation is this note’s, not the article’s; the article’s own spine is below.

The argument, in the author’s own four principles

The most durable part of the piece is not the architecture, it is the definition. Harness engineering is building the environment around the model rather than the model itself — the model reasons and decides, the harness executes, constrains and connects. Four principles follow, and they are the part worth memorising:

1. The model is the only source of decisions. The harness never branches on model output; it executes what the model requests. Any if statement that inspects what the model said and changes behaviour accordingly is the harness making a decision, and that is the line being drawn.
2. Tools are the only interface between the model and the world. Every action — reading a file, spawning a subagent — goes through a typed, schema-validated tool call. There is no second path.
3. Context is a managed resource. What the model sees each turn is curated, compressed and injected deliberately, never accumulated blindly.
4. Permissions are declarative, not procedural. What is allowed, blocked, or requires approval lives in configuration, not scattered through conditional logic.

Principle 1 is the load-bearing one and the easiest to violate. It is what makes the loop generic: the same loop runs a one-line fix and a multi-hour refactor, because all task-specific intelligence sits in the model rather than in the harness’s control flow.

The article’s actual structure

Six phases, each adding mechanisms to the loop without changing the loop itself:

Phases 5 and 6 are entirely absent from the five-layer summary below, as are planning, the dependency graph, mailboxes, streaming, session fork, caching and MCP. If you are using this note to decide whether to read the article, read it: the summary is a slice.

The architecture, in five layers

This grouping is this note’s, drawn from Phases 1–4. Five interconnected layers that turn a probabilistic LLM into a production-grade developer environment:

1. Single-Threaded Master Loop (Agentic Control Engine)

• Role: Central event loop driving the agent through continuous cycles of Perception → Reasoning → Execution.
• Mechanism: The harness passes state to the model, parses structured tool invocation requests, executes those tools locally against the OS/filesystem, and feeds execution results (stdout, stderr, exit codes) back into context until a terminal state or user break is hit.

2. Typed Tool Dispatch Registry

• Role: Schema-validated execution wrappers around system capabilities.
• Mechanism: Maps tool signatures (bash, read_file, write_file, grep, glob) directly to typed, schema-checked handlers. Strict input schemas constrain model outputs, guaranteeing structural validity before touching system APIs or the local shell.

3. Context Management & Memory Layer

• Role: Prevents context rot and token budget exhaustion over long development sessions.
• Mechanism: Combines three dynamic strategies:
  • On-Demand Skill Injection: Dynamically loading project conventions, system prompts, or skill files when triggered by task scope.
  • 3-Tier Conversation Compression: Summarizing older tool execution outputs and turn history before hitting context window thresholds.
  • Disk-Persisted Memory (CLAUDE.md / MEMORY.md): Writing state and learnings directly to disk so agent knowledge survives across terminal sessions.

4. Rule-Based Permission Governance & Event Bus

• Role: Enforces security policies, safe execution boundaries, and human approval without stalling automated workflows.
• Mechanism: Evaluates proposed tool calls against a 3-tier policy hierarchy:
  1. Always Deny: Restricts destructive actions (e.g., executing against production paths, untrusted network calls).
  2. Always Allow: Authorizes safe, read-only operations (e.g., file reads, lint checks) without prompting.
  3. User-Gated Approval: Pauses execution and prompts the developer for explicit confirmation before running risky scripts or file modifications.
  • Lifecycle Hooks: An event bus exposes PreToolUse and PostToolUse hooks to observe, mutate, or block operations in real time.

5. Multi-Agent Coordination & Git Worktree Isolation

• Role: Enables large-scale refactoring and parallel subtasks without collision.
• Mechanism:
  • Context Isolation: Keeps subagent execution logs isolated to avoid polluting the parent agent’s context window.
  • Git Worktree Isolation: Spawns subagents in separate Git worktrees, eliminating filesystem race conditions or branch conflicts when subagents make concurrent edits.
  • FSM Protocols: Manages parent-child task delegation and handoffs using finite state machines. A finite state machine is a design where a thing is always in exactly one of a fixed set of states and only certain transitions are legal — TCP’s LISTEN → ESTABLISHED → TIME_WAIT is the canonical one.

What is observed and what is reconstructed

This is a reconstruction, and the repo name says so — claude-code-from-scratch. Khan is building a harness of this kind in Python and explaining what each mechanism has to do. Read every “Mechanism” line above as “here is how you would build this,” not “here is what Anthropic did.”

The piece does make direct claims about the real product, and it does not mark where the mode changes. Four are stated outright:

• The master loop is stateless and generic, running identically for a one-line fix and a multi-hour refactor.
• The tool registry is the only extension point — a new capability means one new tool with a name, description and input schema.
• Context is actively managed at roughly 92% window usage, older turns summarised and persisted to disk. The article names the compressor wU2.
• Permission governance runs as a pre-execution layer, making safety a structural property rather than a model behaviour.

Separately verifiable from the outside: PreToolUse / PostToolUse hooks, CLAUDE.md on disk, the allow / deny / ask permission tiers, subagent context isolation, and git worktree isolation (an explicit per-agent option that creates a temporary worktree and cleans it up if unchanged).

Two mechanisms are the author’s own implementation and should be read that way. Three-layer compression is presented with concrete constants — a token threshold, a count of recent messages kept verbatim, a markdown memory file — which are his design, not published Anthropic values; only the ~92% trigger is claimed of the real product. The FSM protocol is explicitly not a claim about Claude Code at all: the article says Claude Code coordinates implicitly, because a dispatch call blocks until it returns, and offers the FSM for persistent-teammate architectures where messaging is asynchronous. Four states, one rule — no agent enters REQUESTING while WAITING — which is what removes the deadlock class.

Take the requirements list as the durable content and the mechanisms as one engineer’s answers. As an inventory of what a coding agent needs in order to be reliable, it is unusually complete.

Key Takeaways

1. Model versus harness. An LLM provides reasoning; the harness provides operational reliability, guardrails, state persistence and long-session stamina. Swapping in a better model does not fix a harness problem.
2. Deterministic control around a probabilistic core. Reliability comes from wrapping non-deterministic output in strict schemas, typed handlers, permission gates and execution feedback — the determinism lives outside the model, which is the same reason a kernel validates syscall arguments rather than trusting the caller.
3. A generic loop is the goal, not a simplification. If the loop has to know what kind of task it is running, intelligence has leaked out of the model and into the harness, and it will need maintaining there forever.
4. One extension point. Capabilities arrive as registered tools with a schema, not as new branches in the controller. That is what keeps the loop generic as the tool set grows.
5. Safety is structural or it is not safety. A pre-execution rule layer applies to every call whether or not the model cooperates; a model instructed to be careful is a model that can be argued out of it.
6. Context is a budget with an eviction policy. Compression at a threshold, verbatim retention of recent turns, and a durable on-disk summary is a working set with a backing store — see Context-Rot-and-Governing-Context for why the ceiling arrives earlier than the advertised window.

Related

• Claude Code Usage: Claude Code Has Four Agent Modes
• Context Preservation: Context-Rot-and-Governing-Context