Harness Engineer Roadmap
A path into the layer that turns a model into an agent — the loop, the system prompt, the tool surface, sandboxing, delegation and memory, built and operated in production.
A harness is the layer between a model and the world. It decides what the model is told about itself, which tools it can ask for, what happens when it asks for something irreversible, what it remembers at turn sixty, and when it stops. The model supplies judgement. The harness supplies everything else — and it is ordinary code, written and reviewed like any other part of a system.
This path builds one from the loop upward. It starts with the fifteen lines underneath every agent, then treats the system prompt and the tool schemas as versioned artefacts rather than as text boxes, then adds the sandbox and permission layers that make an agent safe to point at a real repository. The last two phases are about scale and operation: delegating to subagents for context isolation, compacting a session that has outgrown its window, and producing traces that say which layer failed when a run goes wrong.
The reason this material is scarce is that harness code is expensive to develop, cheap to copy and invisible in the finished product, so the capable ones stay private. The compensation is that the skill is portable: models change, and the questions of blast radius, tool surface and what survives compaction do not.
New to Linux and the command line?
This path assumes fundamentals you may not have yet. Our Foundations Pack is out and free — Linux, the shell and Git, with exercises that mark your work and explain why you got it wrong. We're writing an agents pack next; leave your email if you want to hear when it ships.
One email when the pack launches. No spam, unsubscribe any time.
The path, phase by phase
The Agentic Loop
The mechanism underneath every agent, seen plainly. Done when you can write the loop from memory, branch on the stop reason rather than on the response text, and explain why turn forty costs more than turn one. Skip this and you will debug an agent by editing prose, because the loop will look like a black box rather than fifteen lines you own.
3-4 weeks6 SkillsAgentic Loop ConstructionStop Reason HandlingMessage History ManagementToken AccountingAnthropic SDKIteration & Spend BoundingShow details, projects and resourcesSkills you'll master
Agentic Loop ConstructionintermediateStop Reason HandlingintermediateMessage History ManagementintermediateToken AccountingintermediateAnthropic SDKintermediateIteration & Spend BoundingintermediateHands-on projects
- 01Write an agent loop in under fifty lines that runs a single tool and terminates correctly on every stop reason
- 02Bound a loop by both iteration count and cumulative spend, and prove it trips before the budget does
- 03Instrument the loop to print input tokens per turn, and chart how they grow across a twenty-turn session
- 04Deliberately return a malformed tool result and make the loop recover instead of dying mid-task
System Prompt & Tool Surface
The two artefacts the model actually programs against. Done when your system prompt lives in version control with a recorded reason for every change, and your tool schemas refuse the calls you do not want instead of asking the model politely not to make them. Teams that treat these as a text box rediscover the same bugs every quarter.
5-7 weeks7 SkillsSystem Prompt DesignPrompt Versioning & ReviewTool Description WritingJSON Schema DesignError Messages as Model InputPrompt CachingTool Surface SizingShow details, projects and resourcesSkills you'll master
System Prompt DesignadvancedPrompt Versioning & ReviewintermediateTool Description WritingadvancedJSON Schema DesignadvancedError Messages as Model InputintermediatePrompt CachingintermediateTool Surface SizingadvancedHands-on projects
- 01Put a system prompt under version control and write the commit message that justifies each change for a month
- 02Take a failing instruction and move the fix down into a schema constraint that makes the bad call impossible
- 03Rewrite a tool's error returns so a failed call steers the next attempt instead of ending the task
- 04Measure the token cost of your tool definitions per turn, then cut the surface in half and compare selection accuracy
- 05Build a harness whose stable prefix lets caching pay, and measure the difference across a long session
Sandbox, Permissions & Hooks
The layer that decides what happens when the agent asks for something dangerous. Done when you can state the blast radius of your worst single tool call, confine a path without being fooled by a symlink, and explain why consent fatigue makes a naive approval prompt less safe than no prompt at all. This phase is where an impressive demo becomes something you would point at a real repository.
5-7 weeks7 SkillsSandboxing & Process IsolationPath ConfinementPermission Model DesignPrompt Injection DefenceLifecycle HooksContainersLeast PrivilegeShow details, projects and resourcesSkills you'll master
Sandboxing & Process IsolationadvancedPath ConfinementadvancedPermission Model DesignadvancedPrompt Injection DefenceadvancedLifecycle HooksintermediateContainersintermediateLeast PrivilegeadvancedHands-on projects
- 01Write a path confinement check that resolves symlinks and survives an adversarial test suite you wrote to break it
- 02Classify every tool in your harness by reversibility and wire the irreversible ones to an explicit confirmation
- 03Run the agent inside a container with no network egress and get a real task done anyway
- 04Plant a prompt injection in a file the agent will read, then show that your permission layer bounds what it achieves
- 05Add a post-edit hook that runs the formatter and type-checker, and feed the failures back to the agent as input
Delegation & Long Sessions
What a harness does when one window is not enough. Done when you delegate for context isolation rather than for the appearance of parallelism, and when a sixty-turn session still knows the task it was given in turn one. Most agents that impress for ten minutes and fall apart over an afternoon fail exactly here.
4-6 weeks6 SkillsSubagent ArchitectureContext IsolationTask Handoff DesignHistory CompactionDurable MemoryConcurrency ControlShow details, projects and resourcesSkills you'll master
Subagent ArchitectureadvancedContext IsolationadvancedTask Handoff DesignadvancedHistory CompactionadvancedDurable MemoryintermediateConcurrency ControlintermediateHands-on projects
- 01Delegate a broad search to a subagent and measure the parent's window with and without the delegation
- 02Write a handoff prompt precise enough that the subagent needs no follow-up question
- 03Implement compaction that preserves the goal, the decisions and their reasons, and drops what can be re-read
- 04Run a session past the point where compaction triggers and verify the agent still knows what it was asked
- 05Make two subagents work concurrently without editing the same files, and detect it when they try
Operating a Harness in Production
Everything that separates a harness that works on your machine from one other people depend on. Done when a failed run leaves you a trace that says which layer failed, and when a prompt change ships only after an evaluation says it helped. Without this phase you will be tuning a system whose behaviour you can only describe anecdotally.
5-7 weeks6 SkillsAgent Tracing & ObservabilityEvaluation Harness DesignCost & Latency BudgetingRegression Testing for AgentsFailure Triage by LayerOpenTelemetryShow details, projects and resourcesSkills you'll master
Agent Tracing & ObservabilityadvancedEvaluation Harness DesignadvancedCost & Latency BudgetingadvancedRegression Testing for AgentsadvancedFailure Triage by LayeradvancedOpenTelemetryintermediateHands-on projects
- 01Emit a trace per run that records every tool call, its arguments, its result size and its latency
- 02Build a twenty-case evaluation set and gate every system prompt change on it
- 03Triage ten real failures and attribute each to the loop, the prompt, a tool, the sandbox or the model
- 04Track cost and latency per completed task, not per call, and find the tool that dominates both
- 05Assess an agent you did not write from the outside and document what you inferred about its harness
Frequently asked questions
Related roadmaps
- AI Agents Engineer RoadmapA path from LLM and programming fundamentals through agent orchestration, tool use, and production deployment for building autonomous AI agent systems.
- AI Security Engineer RoadmapA defensive security path for engineers who secure LLM and agent systems, covering AI threat modelling, prompt injection defence, supply chain integrity, agent permissions, guardrails, governance and incident response.
- Platform Engineer RoadmapThe path DevOps engineers move into — building an internal developer platform as a product, covering Kubernetes as substrate, IaC at scale, GitOps, golden paths, portals, policy, multi-tenancy and adoption.