The harness: how we make AI agents build real software

Every page on this site, the portal behind it, and the client websites we run were built by AI agents. Not autocompleted by AI while a person typed, built by agents that plan, write, test, and ship code while we review and direct. The difference between that working and that producing an expensive mess is a set of plain markdown files we call the harness. This guide shows you the real ones from our repository.

A harness is everything an agent reads before it writes: what the project is, what good looks like, which steps are never optional, and what it must do before claiming something is finished. Agents are smart and fast and they forget everything between sessions. The harness is where the memory of how you work actually lives.

Start with one file that tells the truth

The root of our harness is a file called CLAUDE.md that every agent loads on start. Most teams write these like a README, a polite tour of the folders. Ours reads like standing orders, because that is what an agent actually needs. Here is a piece of it, unedited:

## Non-negotiable workflow

1. **Design work uses the frontend-design skill** plus the house-styles
   skill to pick the correct aesthetic before any UI code.
2. **Every UI change is verified visually** with the Playwright loop:
   screenshot, critique, iterate. No blind merges of visual work.
3. **Full PR loop, no dangling PRs**: branch, push, PR, poll the
   review check, fix findings, merge. Never leave a PR waiting.
4. Read the lifecycle doc before writing code; keep PRs small.

Notice what those four lines are doing. They are not describing the codebase, they are closing the gaps where agent work quietly goes wrong: skipping design decisions, merging screens nobody looked at, and abandoning half-shipped branches. Every rule in the file earned its place by something going sideways once. When an agent misbehaves, we do not just fix the output, we fix the file, and the mistake stops recurring across every future session.

Give the rules somewhere portable to live

The root file stays short because the detail lives in a folder of shared docs that agents are told to read at the moment they need them. Ours covers the engineering lifecycle, how large a pull request is allowed to get, how to write copy that does not sound like a robot, and how we run design work. A rule that lives in a doc gets applied by every agent on every task. A rule that lives in someone's head gets applied when that someone is watching.

A PR should be reviewable in one sitting. If the diff mixes a
refactor with a feature, split it. If a reviewer would need to
hold more than one idea in their head to say "this is safe,"
it is two PRs. Small PRs are not slower; they are the reason
the merge queue keeps moving.

Make verification a step, not a virtue

The single biggest upgrade to our agent output was refusing to let “it should work now” count as done. Agents are confident writers, and confidence is not evidence. So the harness makes evidence mechanical. UI work runs through a screenshot loop: the agent starts the app, takes real screenshots at phone and desktop sizes, critiques its own result against the design standard, fixes what it finds, and repeats until the screenshots pass. Code runs through gates: linting, type checking, and the test suite, before any pull request opens. Then a second AI reviews the PR itself.

We learned to distrust self-reported success the hard way. An agent once reported a branch pushed and a PR opened when neither existed, twice in one day. The fix was not scolding it, the fix was a harness rule: ship claims get verified against the actual systems before anyone acts on them. Here is the note we keep in our agent instructions:

Builders have fabricated commit/push/PR reports; always
confirm via git/gh before acting on a ship claim. Trust the
repository, not the report.

That sounds paranoid until you run agents daily. Then it just sounds like bookkeeping. The pattern generalizes: for anything an agent claims, prefer a check the computer can run over a sentence the model can write.

Divide the work like a studio, not a solo act

One agent doing everything produces the same problems as one person doing everything: it loses the thread, mixes concerns, and burns its context window on work below its pay grade. Our harness defines roles instead. A planning model thinks through architecture and design direction. A managing model owns the task list, spawns workers, reviews their output, and runs the merge process. Builder agents actually write the code, one scoped task each, in their own isolated copy of the repository so parallel work never collides.

Fable and Opus are **orchestration layers, not builders**. If an
orchestrator catches itself writing components or hand-fixing
CSS across files, that is a role violation — stop and delegate.
Sonnet **actually builds stuff**: page builds, component work,
content edits, migrations, tests.

Two things make this work in practice. Scoped briefs: a builder gets one task, the exact standard to meet, and the gates it must pass, not a vague ambition. And review on return: the orchestrator reads what came back before it ships, the way a lead reviews a junior's branch. The expensive model spends its judgment where judgment matters, and the fast model spends its speed where the work is mechanical. We wrote more about the economics of this split in the model tiering guide.

Let the harness learn

The harness is not a document you write once. Ours grows a line almost every working day, because the rule of thumb is simple: if you correct an agent twice for the same thing, the correction belongs in a file. Some of our rules would look oddly specific to an outsider. There is one banning a particular rhythm of AI-sounding marketing copy. There is one requiring photography on every design because agents left to themselves ship text-only pages. There is one about deleting build artifacts after merges because a fleet of agents once filled the whole disk in an afternoon. Each is a scar with a lesson attached, and each means that mistake now gets made zero times instead of occasionally.

This is the part most teams miss when they evaluate AI coding tools: the model is maybe half the outcome. The other half is whether the humans built a place for the lessons to accumulate. Models improve every few months on their own. Your harness only improves if you write things down.

Where to start with yours

Start embarrassingly small. One CLAUDE.md at the root of your repository with three sections: what this project is in two sentences, the commands to build and test it, and the two or three rules you find yourself repeating. Add a verification step the agent cannot skip, even if it is just “run the tests and paste the output.” Then live with it for a week and write down every correction you make twice. That file will be worth more than any prompt trick you will ever learn.

If you want the deeper version of this, the membership includes our full playbook on agent harnesses, and we build harnesses for client teams as part of our AI consulting work.