Harness engineering: how to build a reliable AI agent
Articles: 8
Harness engineering is the discipline of building an environment around a language model in which an AI agent reliably does real work. The formula of the topic: Agent = Model + Harness. The same model in one project works like an experienced developer, while in another it loses context and reports that a broken feature is ready. The difference is almost always in the harness, not in the model.
This guide is a map of the topic. It collects the key concepts and the order in which it is convenient to learn them. Each topic is covered in detail in a separate article.
The five subsystems of the harness
- Instructions — CLAUDE.md and AGENTS.md files, topic documents and skills: what the agent knows about the project.
- Tools — shell, file editing, browser, MCP servers: how the agent acts.
- Environment — a sandbox, a container, an isolated working copy: where the agent runs commands.
- State — plan and progress files, git history: memory between sessions.
- Feedback — tests, linters, hooks, an independent verifier: how the agent learns about its mistakes.
The subsystems form a closed loop. Remove any one of them and the loop breaks: without checks the agent does not see its mistakes, without state every session starts from zero.
Where to start
If the topic is new to you, start with the article on what harness engineering is and how it differs from prompt and context engineering. A short definition with an example is in the article on the agent harness.
Then move on to practice. The first file everyone runs into is the project instructions: what to write in CLAUDE.md and AGENTS.md, what not to write, and why the agent ignores a rule that is stated directly in the file.
Once the agent is already working in a project, the question of reliability arises. A step-by-step plan leads from a log of failures and the MTBF and MTTR metrics, through cheap rollback, feedback loops and memory in files, to an autonomous loop in which the agent works for hours without supervision.
Main principles
- The agent is not broken — the environment is. First look for the gap in the harness, not for a different model.
- Start with feedback: a check command gives more than a page of instructions.
- Instructions are a map, not a textbook: a short entry file and details on demand.
- What matters lives in files, not in the context window.
- Measure: a log of failures instead of feelings.
All the subsystems and the assembly of the harness as a whole are covered in practice in the harness engineering course.