Harness Engineering for AI Coding Agents: A Beginner's Guide

The Learn Harness Engineering course groups a harness into five subsystems: instructions, tools, environment, state, and feedback. Instructions tell the agent how this repository works. Tools let it inspect and change the system. The environment makes those actions reproducible. State carries decisions across sessions. Feedback tells the agent whether the result is correct.

Score each subsystem from one to five. Then inspect recent failures. If an agent used the wrong package manager, the instruction or environment layer failed. If it claimed success while the payment button did nothing, the feedback layer failed. Fix the layer that caused the observed failure instead of changing models by default.

An agent cannot follow an architecture decision that exists only in a meeting, chat thread, or a senior engineer's memory. Put stable knowledge beside the code: product behavior, architecture, setup, security boundaries, deployment rules, and known failure modes.

Do not copy every document into one file. OpenAI reports that a short AGENTS.md works better as a map to deeper repository documentation. This progressive disclosure keeps the starting context small while making detailed guidance available when a task needs it.

A useful root instruction file explains the project's purpose, stack, important directories, standard commands, hard boundaries, and definition of done. Link to detailed documents instead of repeating them. Rules that protect data, security, billing, or architecture should be explicit and testable.

Keep advice local when it only applies to one part of a monorepo. A frontend package can have its own instruction file with browser-test guidance while the root file stays focused on repository-wide behavior.

Broad goals encourage an agent to start several related changes and finish none of them. Give it one vertical slice with an observable outcome. Include the allowed scope, non-goals, acceptance criteria, and commands or actions required to prove completion.

For work that spans sessions, store features as structured records. The scheduler, implementer, verifier, and next session should all read the same status and acceptance criteria. Change status only after the evidence exists.

Static checks catch syntax, types, formatting, and many regressions. They do not prove that connected parts work together. Add the narrow checks first for fast feedback, then run the full pipeline that exercises the user-visible path.

A payment feature is a useful example. Rendering the checkout page proves very little. The verification must click Pay now, use the provider's test path, observe network and browser errors, and confirm both success and failure states. Record the exact command or manual procedure in the task so a later session can repeat it.

Context compaction and chat history are not dependable project memory. Anthropic's long-running agent work uses repository artifacts and git history to bridge sessions. A small progress file should state what changed, why key decisions were made, which checks passed, what failed, and the next bounded action.

End each session in a state another engineer could resume. Remove debug artifacts, keep the build understandable, and distinguish verified work from incomplete work. Never mark a feature complete because files were created.

Agents correct themselves faster when they can inspect browser state, logs, network requests, traces, and test artifacts. Give them the smallest safe tool access that can observe the behavior under test. A screenshot alone is weaker than a browser trace plus console and network output because it shows the surface, not the cause.

Increase autonomy only after the loop has a bounded goal, a retry limit, a stop condition, and an escalation path. Start with one agent completing one task. Planner, reviewer, or graph-style workflows add coordination cost and should solve a measured bottleneck, not decorate an unreliable loop.