What Is Harness Engineering? When the AI Agent Problem Shifts From Writing Prompts to Operating Architecture

Quick answers

• The core formula: Agent = Model + Harness. If the language model (GPT, Claude, Gemini) is the "brain", the Harness is the entire environment, toolset and process wrapped around it that turns that brain into an entity that can actually do work.
• Working with AI has evolved through 3 stages: Prompt Engineering (writing the request cleverly) → Context Engineering (feeding the right information at the right time) → Harness Engineering (organizing workflows, self-testing and safety controls for the Agent).
• A modern harness such as Claude Code has 9 components: the main loop, context management, tools and skills, sub-agents, built-in skills, session memory, system-prompt assembly with prefix caching, hooks, and permissions/safety.
• When an agent performs poorly, do not rush to switch to a stronger model — optimize the harness first: give it enough information and tools, block errors with mechanisms instead of verbal reminders, build a feedback loop, and use a sandbox when a high level of autonomy is needed.
• Frameworks and harnesses are not the same: a framework (LangChain, AutoGen) is a set of loose tools for assembling your own setup; a harness (Claude Code, Cursor, Codex) is an environment with the workflow already built in, ready for the agent to step into and operate.

What is Harness Engineering?

Harness Engineering is the practice of designing and optimizing the "operating layer" around an AI model: the tools the agent is allowed to use, how context is supplied and cleaned up, how work is broken down into steps, how results are self-checked, and the permission and safety mechanisms in place. If Prompt Engineering cares about the instruction, and Context Engineering cares about the information, then Harness Engineering cares about the entire working system — the factor that decides whether an AI agent can handle long, complex work reliably.

Why Agent = Model + Harness: the lesson of the pho restaurant

To picture it, the original article borrows the pho-restaurant analogy from a video by Việt Nguyễn AI. Suppose you hire a genius chef (the Model): he can cook anything, but he has two weaknesses — he does exactly and only what is written on the order ticket (the Prompt), and he only remembers what is currently laid out on the kitchen counter in front of him (the Context Window). Anything cleared off the counter is forgotten completely.

A great chef alone does not make a working restaurant. Whether the place runs well also depends on shift scheduling, record keeping, tasting dishes before they go out, ingredient storage and safety rules — that is the Harness. The same Model, placed in a messy "kitchen", will produce noticeably worse results than in a well-organized one.

How do the three stages — Prompt, Context and Harness Engineering — differ?

Stage 1 — Prompt Engineering (writing a clear order ticket). In the early days the "counter" was tiny: the context window held only a few thousand tokens (according to the author's slide, context windows grew from about 2K tokens to over one million tokens in just 5 years). The only way to work was to write extremely detailed request tickets. The weakness was the one-shot style: cook once, serve, done — no fetching extra ingredients, no tasting, and no self-correction when something went wrong.

Stage 2 — Context Engineering (laying the right ingredients on the counter). As the counter grew wider, three main techniques emerged to supply "ingredients" intelligently: Tool Calling — the chef goes into the pantry himself to fetch ingredients and work with them; MCP (Model Context Protocol) — a common connection standard, like standardized sockets for plugging in external equipment; and RAG — the recipe handbook, where you find and open exactly the right page for the dish at hand. But when the job is huge (like "cook a 500-table feast in 12 hours"), the counter still fills up. When the agent clears the counter itself and summarizes the context (Context Summarization), it easily misremembers or drops items — leading to code that still has bugs and features that do not run, yet the agent reports "completed".

Stage 3 — Harness Engineering (running the whole kitchen by process). Instead of letting the chef work 12 hours straight at an ever-messier counter, the job is broken down from the requirements document (PRD) into a checklist (in JSON form). In each "shift", the agent starts with a brand-new context — a clean counter — picks exactly one item from the list, finishes it, runs tests to check ("tastes the dish"), logs the result, and only then moves to the next shift. This shift-based approach lets the agent work for long stretches without its memory descending into chaos.

Stage	Pho-restaurant metaphor	Focus	Remaining weakness
Prompt Engineering	Writing a clear order ticket	The input instruction/request	One-shot work, no self-checking, no self-correction
Context Engineering	Laying the right ingredients on the counter	Right information, at the right time, within the context limit (Tool Calling, MCP, RAG)	Oversized jobs overflow the context; summarization misremembers and drops things
Harness Engineering	Running the whole kitchen by process	Task splitting, shifts, self-testing, permissions and safety	Requires system design, not just prompt-writing skill

What are the nine components of a modern harness?

Taking Claude Code as the example, the original article identifies 9 components that make up a modern harness:

1. Main Loop: essentially a "while" loop — read the instructions, call a tool, receive the result, check again, and repeat until the job is done or the loop limit (Max Turns) is reached.
2. Context Compaction: when the context fills to about 80–90%, the system automatically keeps the most recent important information, compresses older steps and deletes junk data.
3. Tools and Skills: Tools are basic operations (reading/writing files, running commands), like knives and cutting boards; Skills are a project's own know-how, packaged in Markdown files — the agent opens a Skill file only when the work reaches that step, to save memory.
4. Sub-agents: like assistant cooks, each with their own workstation and limited permissions (one only searches, one codes, one runs tests). When done, they send only the final result back to the "head chef", keeping the main context clean.
5. Built-in Skills: built-in workflows such as reading and fixing code, creating Git commits, opening pull requests and running tests.
6. Session Memory: a logbook that only allows appending to disk (an append-only log). If the system crashes mid-way, simply replaying the log from the start restores the in-progress state.
7. System Prompt assembly and Prefix Caching: the system automatically gathers the general rules and the per-project rules (CLAUDE.md, AGENTS.md files). The static instructions always go first and the dynamic parts last, to exploit Prefix Caching and sharply reduce cost and latency across hundreds of loop iterations.
8. Hooks: a Pre-tool Hook reviews, blocks or edits a command before it runs; a Post-tool Hook logs and audits after it runs. Hooks let a business attach its security rules without modifying the harness core.
9. Permissions and Safety: levels from Read-only, through Workspace Write, to Full Access. Sensitive commands such as deleting data or intervening in the system are blocked until a human confirms them.

How do a framework and a harness differ?

In short: a framework such as LangChain or AutoGen is a set of loose tools — libraries for developers to assemble their own "kitchen". A harness such as Claude Code, Cursor or Codex is a kitchen with the workflow already built in: tools, looping, context management and permissions are integrated, and the agent (and the user) just steps in and operates. In practice, many teams do not build a harness from scratch; they customize an existing harness to fit their project's process.

What are the five field principles for working with AI agents?

1. Do not rush to change the Model when results are poor. The same chef cooks worse food in a messy kitchen than in a tidy one. Before blaming the Model, check whether the agent has been given enough information and tools.
2. Optimize from what you already have. There is no need to code an AI agent from scratch. Writing clear CLAUDE.md and AGENTS.md files, crafting proper Skills and attaching Hooks to your project — that is Harness Engineering.
3. Block errors with mechanisms, not with words. Repeating an instruction in the prompt still leaves times when the AI forgets. Use hard mechanisms such as folder permissions, Pre-tool Hooks or a mandatory unit-test suite to lock errors out.
4. Always create a Feedback Loop. A chef must taste the dish to know if it is too salty or too bland. Give the agent tools to run tests, read error logs or screenshot the interface, so it can tell right from wrong and fix itself.
5. Use an isolated environment (Sandbox) when high autonomy is needed. If you want the agent to run dozens of steps without constantly asking permission, place it in a Docker container or a virtual machine with pre-limited resources, guaranteeing the safety of the main system.

Frequently asked questions

How is Harness Engineering different from Prompt Engineering? Prompt Engineering optimizes the input instruction for a single call; Harness Engineering designs the whole operating environment — tools, context, task-splitting process, testing, memory and permissions — so the agent can do long, complex work reliably.

Which techniques belong to Context Engineering? Three main ones: Tool Calling (the agent calls tools to fetch more information and take actions), MCP (a common connection standard for external systems) and RAG (document retrieval that brings only the relevant part into context).

Where should a beginner start with Harness Engineering? From what already exists: write the project instruction files (CLAUDE.md, AGENTS.md) really clearly, package repeated workflows into Skills, attach Hooks to control sensitive commands, and set things up so the agent can always run tests after each task. There is no need to build an agent from scratch.

What is a sub-agent and what is it good for? Sub-agents are child agents with their own context and permissions, each specialized in one job (searching, coding, testing). They return only the final result to the main agent, keeping the main context free of clutter and letting each job be done in a focused space.

Why not just switch to a stronger Model when an agent works poorly? Because most poor results come from the harness, not the Model: missing information, missing tools, no tests for self-checking, or an overloaded context. Optimizing those factors usually improves results more clearly than changing the Model — and costs less.

---

Source: the article "Decoding Harness Engineering: when the AI problem shifts from writing prompts to operating architecture" by Lữ Minh Khương in the VGU Tech Alumni group on Facebook, posted on November 5, 2026. The original content is based on an analysis video by Việt Nguyễn AI. Figures on context-window growth are cited from the author's slide.