Vertical Harness Engineering
A practical Vertical Harness Engineering workshop with interactive machine diagrams, Claude Code demonstrations, practical exercises, context design, tool permissions, evaluation and recovery.
From general agents to specialists
Learn what a harness is, how domain knowledge, tools and rules make it vertical, and how to evaluate the result. By Harshith Vaddiparthy. The interactive edition includes progressive slide navigation, animated mechanical models and a free PDF for confirmed newsletter readers. The companion article explains the full method.
Vertical Harness Engineering
Build a specialist around a real job.
One workflow. Working files. Tested results.
What is a harness?
The model is the engine. The harness makes it usable.
Context tells it what matters.
Tools let it act.
Controls and feedback guide the run.
Three levels of harness engineering
Choose your starting point.
Cowork · ready car.
Claude Code · tuneable race car.
Build your own · assemble the parts.
What makes a harness vertical?
A vertical harness specializes the system for one domain and recurring task.
Meet the support specialist
Turn a damaged-lamp ticket into a reviewable resolution.
Open the ticket.
Find its order and policy.
Preview the resolution pack.
Expected result: A draft ready for review.
Open the workspace together
Find the inputs, task and expected output.
Open TASK.md.
Locate the source records.
Ask Claude Code for its plan.
Expected result: A concrete plan and file map.
Prompt to adapt: Read TASK.md and list the exact ticket, order, current policy, expected output files and next three actions. Do not create the output yet. Work only inside this synthetic lab.
Give the specialist its context
Project instructions guide work. Domain evidence supplies the facts.
Inspect CLAUDE.md and policy.
Create a sourced working brief.
Check its amount and dates.
Expected result: progress/brief.md
Prompt to adapt: Read CLAUDE.md, TASK.md, records/ticket-T-104.json, records/order-O-204.json and policies/refunds-current.md. Write progress/brief.md with the goal, authoritative amount, relevant dates, policy source, discrepancy and next action. Keep original files unchanged. Explain why the current policy and order are authoritative.
Turn the method into a skill
Use a real SKILL.md and load detail when needed.
Inspect the skill’s procedure.
Follow its reference when needed.
Produce the resolution pack.
Expected result: A reusable method and local drafts.
Prompt to adapt: Read .claude/skills/support-resolution/SKILL.md. Explain what the name and description reveal before the procedure is loaded. For T-104, identify when its source-authority reference and message template are needed. Then follow the skill to prepare the local resolution pack. Preserve original sources and the checker; report only observed results.
Observe what the tools actually return
A requested action and its result are different things.
Read the order result.
Run the permission simulation.
Finish the permitted draft.
Expected result: A visible result and precise state.
Prompt to adapt: Run python3 simulate.py permission. Explain the proposed action, actual result and useful work still allowed. Read the order record and show the returned amount and source ID. Keep this workflow local and draft-only.
Take a break
Save your brief and the next action.
Return with your workspace open.
Trigger the workflow. Resume its state.
Automation starts the same job; the checkpoint preserves its progress.
Run the trigger simulation.
Save a truthful checkpoint.
Resume from the recorded state.
Expected result: One job and a usable handoff.
Prompt to adapt: Run python3 simulate.py trigger and explain what happens to the duplicate event. Then read progress/checkpoint-example.md, verify the files it references and write progress/checkpoint.md with your actual state and exact next action. This is a local simulation; install no schedule or hook.
Build your own vertical workflow
Choose one recurring job and produce one useful artifact.
Specify the domain job.
Build one local path.
Show the resulting artifact.
Expected result: A small specialist you can inspect.
Prompt to adapt: Use templates/harness-contract.md to specify one recurring domain job using synthetic or public examples. Save the contract and a proposed output schema under output/my-workflow/. Implement one local artifact-producing path there, preserving this lab’s original evidence and checker. State which parts are implemented and which remain a plan. If adapting another domain, propose its own acceptance conditions instead of reusing Northstar facts.
What is an eval?
A repeatable check that tells you whether the job was done well.
Predict the bad answer’s failures.
Run the checker.
Read the failed conditions.
Expected result: Evidence, not confidence.
Prompt to adapt: Inspect fixtures/bad-resolution.json and predict its failures against the original records and policy. Run python3 check_resolution.py fixtures/bad-resolution.json. Explain what the checker establishes and what it does not establish. Preserve the fixture, checker and original evidence.
Repair. Rerun. Test another case.
Improve the artifact using evidence, then test the same conditions again.
Repair a copy from sources.
Rerun the unchanged checker.
Add a partner’s failure case.
Expected result: A tested repair and one new eval.
Prompt to adapt: Repair a copy of fixtures/bad-resolution.json using the original records and current policy. Write output/repaired-resolution.json. Do not edit the checker, records or policy. Run python3 check_resolution.py output/repaired-resolution.json. Then propose one additional domain-specific case with its expected behavior written before execution.
Build for the job. Test against the job.
Your specialist is its working system and the results it can demonstrate.
A domain contract.
A useful artifact.
An evaluation loop.
What is a vertical harness?
In this guide, a vertical harness means an agent harness specialized for a particular domain and recurring job. Its domain records, procedures, tools, outputs and evaluation criteria equip the agent to do that job. This is a working definition rather than a universal industry standard.
How does a vertical harness differ from a general agent harness?
The general harness provides capabilities such as tool execution, context handling and state. A vertical harness configures those capabilities around a specific job, such as support resolution or invoice reconciliation, using domain-specific knowledge and success criteria.
Does a vertical harness require a fine-tuned model?
No. Specialization can live in the surrounding context, procedures, tools, workflow and evaluations while using the same general-purpose model. Fine-tuning is a separate decision that requires evidence of a need.
What is harness engineering?
Harness engineering is the design of the system around an AI model that helps it complete work: instructions, context selection, tools, permissions, execution loops, state, evaluation and recovery. The exact boundary varies by product and team.
How is harness engineering different from prompt engineering?
Prompt engineering shapes instructions for a model response or run. Harness engineering also controls the environment in which the run happens, including which evidence is available, which actions can execute, how progress is stored and how completion is checked.
How is context engineering related to harness engineering?
Context engineering selects and maintains information for the model's current decisions. It is an important part of a harness, alongside execution, permissions, state management and verification.
Is Claude Code an agent harness?
Claude Code is an agentic coding product with a tool loop and surrounding capabilities. Anthropic's Agent SDK documentation describes exposing the tools, agent loop and context management that power Claude Code as a programmable library.
Do I need to build a custom agent framework?
Often you can begin by configuring an existing agent product with a concise project map, source rules, tool boundaries and acceptance checks. Build custom orchestration when a concrete requirement cannot be met by the simpler setup.
Does an MCP connection make an agent reliable?
MCP can expose tools and data, but reliability also depends on the task contract, authorization, source quality, execution behavior, evaluation and recovery. A connection does not establish that an action is appropriate or that it completed.
What should I test in an agent harness?
Test representative successful tasks plus missing or conflicting evidence, denied actions, ambiguous inputs, timeouts, repeat requests and resumption. Check exact requirements with code and calibrate human or model judgment for requirements such as relevance and clarity.
How should an agent recover after a tool timeout?
A timeout may leave the action's outcome unknown. Before repeating a consequential operation, inspect its state or receipt using the tool's supported operation identity and replay semantics. If state cannot be established, keep the result explicit as unknown and reconcile it.
What is the role of skills in a harness?
A skill packages reusable instructions and may include references, scripts and assets. Loading the relevant procedure and supporting material on demand can keep context focused. A skill does not itself grant credentials or permission to perform an action.
How do scheduled tasks and hooks fit into a harness?
They are ways to start a workflow at a time or in response to an event. The run still needs its task contract, scoped tools, duplicate prevention, limits, verification and recovery. A trigger does not create new authority.
Does this workshop require an API key or external connector?
The teaching lab uses local synthetic records, a standard-library checker and prepared fallback artifacts. Participants can use an existing Claude Code environment or complete the contract and evaluation exercises without a live model connection.
Is the Northstar example a real customer deployment?
No. Northstar Store, its records, policies, amounts and demonstration outputs are original synthetic teaching material. The lab demonstrates engineering controls; it does not represent measured customer results.