Harness Engineering

Harness Engineering (HE) is an advanced methodology for software development in the age of Artificial Intelligence. While vibe coding allows for quick experimentation, Harness Engineering is designed for building production-grade systems that are coherent, maintainable, and trustworthy.

New to harness concepts? Start with the Fundamentals track on Harness Engineering for the five-layer production model, then return here for the full student guide.

The fundamental metaphor describes the relationship between the developer and the AI:

Role	Metaphor	Responsibility
AI Agent	The Horse	Powerful, tireless, generates vast amounts of code rapidly
Environment	The Harness	Tools, constraints, and feedback loops that channel capability
Human	Holds the reins	Intelligent work — destination, terrain, when to slow down

The human performs the intelligent work — choosing the destination, reading the terrain, knowing when to slow down — while the AI performs the physical work of coding.

Without a harness, developers are often "trampled" by the AI, resulting in systems that fail to compile or require constant manual clean-up.

Vibe coding — where a developer accepts all changes without review and passes errors back to AI — is suitable for throwaway weekend projects but fails in production. Harness Engineering addresses five specific failure patterns:

Failure	What happens	HE solution
One-shot Hero	Entire full-stack app in one prompt; context overflow and hallucinations	Break tasks into manageable windows via specs
Premature Victory	Agent declares "done" before task is finished	Strict Definition of Done in specifications
Session Amnesia	Every new session starts from zero	Progress files, session logs, bootstrap scripts
Fake Readiness (200 OK Fallacy)	Superficial test passes; end-to-end logic untested	External sensors with binary pass/fail
Single Process Bias	Same agent implements and validates	Separate builder and independent validator agents

OpenAI's experiments — generating over one million lines of code with only three engineers — highlighted three essential practices that define this discipline:

1. Context Engineering — treat the context window as a precious, limited resource.
2. Architectural Constraints — enforce rigid models instead of "anything goes."
3. Entropy Management — garbage-collect inconsistencies before agents replicate them at scale.

The sections below expand each pillar with practical implementation guidance.

AI context is a precious resource. Large instruction files crowd out the actual task.

Table of contents, not encyclopedia: Keep the main agent markdown file (agents.md or CLAUDE.md) under 100 lines. Use it to link to maps, execution plans, and design specs — not to duplicate every rule inline.

Dynamic context: Provide the agent with real-time observability data, logs, and traces so it can detect and fix its own bugs when sensors fire.

Environment legibility: A new session should understand project structure within minutes, not hours. Predictable folder layout and short index files beat massive monolithic prompts.

Unlike the "anything goes" approach of vibe coding, HE enforces rigid models.

Unidirectional flow: Dependencies must only flow in one direction:

Types → Config → Repo → Service → Runtime → UI

Sensor enforcement: Use custom linters and structural tests to block the agent from violating the design. Error messages in these tools should provide remediation instructions so the AI can fix the violation itself — not just "error on line 42."

Design as code: Architecture is not documentation the agent might ignore; it is enforced by the build pipeline.

AI agents are pattern replicators. If a codebase contains inconsistencies, the AI will reproduce them at scale.

Background agents: Run agents specifically to scan for deviations and automatically fix them — architectural garbage collection.

Fix the harness, not the code: If an agent fails, do not fix the code manually as the default response. Identify the missing capability in the harness, make it legible and enforceable, then have the AI write the fix.

Legibility over heroics: A messy codebase trains messy agents. Entropy management keeps the environment readable for every future session.

Controlling an AI-driven system requires two engineering mechanisms working together.

Feed-forward (Preventive Control)

Instructions and constraints provided before execution. Goal: increase the probability of success by defining a clear path forward.

Components: Technical specifications (Specs), architectural rules, agent instructions (agents.md, CLAUDE.md), pre-defined skills.

GPS analogy: The route planned before leaving — it tells the horse exactly where to go and what rules to follow.

Spec-Driven Development (SDD): A pure form of feed-forward where the specification is the single source of truth guiding generation.

Feedback (Corrective Control)

Observing output after execution and correcting errors via sensors.

Components: Linters, unit tests, type checkers, automated review agents.

GPS analogy: Recalculation when you miss a turn — detects deviation and forces correction in real time.

The Rule of Sensors

The agent should never be the judge of its own work. Sensors must be external tools that return a binary result (pass or fail). This prevents premature victory based on superficial checks like a 200 status code.

Feed-forward defines the what and how. Feedback proves the system works. Relying only on the route leads to failure at the first error; relying only on recalculation lacks direction. HE combines both.

To solve session amnesia, developers use a local memory layer — often an Obsidian vault (markdown-based knowledge base) that agents read and write directly.

Session logs: After every session, the agent writes structured summaries — decisions made, outstanding items, context that matters for the next run.

Progress files: Markdown files recording what has been completed in a sprint, allowing new sessions to pick up exactly where the last one ended.

CLAUDE.md / Agent Constitution: A root file containing standing instructions, vault structure, and session protocols — kept short, linking to deeper specs.

Genuine continuity: The agent does not start from scratch because it reads the history of previous sessions at bootstrap.

For maximum environment legibility, follow a predictable structure:

Path	Purpose
/.codestudio/prompts/	Standardized prompt files (compile.prompt.md, test.prompt.md)
/docs/specs/	Single source of truth — Markdown specifications of application design
/AI/sessions/	History of session logs and progress files for memory persistence
/src/	Source code organized into rigid layers from architectural constraints

Predictable structure reduces token waste on rediscovery and makes feed-forward instructions shorter.

To eliminate single-process bias, use separation of concerns across agents:

1. Orchestrator — receives the task, loads the spec contract, initiates work.
2. Builder agent — implements against the contract in isolation.
3. Validator agent — independent process whose sole goal is to find errors against the specification.

The validator must not share the builder's context or mission. Its incentive is to break the output, not to ship it. This mirrors the Evaluator-Optimizer pattern from Agent Architectural Patterns applied to harness engineering practice.

Harness Engineering shifts the focus of the human developer from writing code to designing environments.

As an engineer in this ecosystem, your primary value is no longer manual implementation, but the creation and maintenance of the harness — the system of specifications and sensors that ensures the AI horse arrives at the correct destination safely and efficiently.

Practical next steps:

• Audit your current project for the five vibe-coding failure patterns.
• Shorten CLAUDE.md / agents.md to a table of contents under 100 lines.
• Add one external binary sensor (test or linter) the agent cannot override.
• Start a session log in /AI/sessions/ before your next agent run.