9.3 The Validation Harness

Hooks decide when checks run. This lesson is about the checks themselves — the validation harness: the set of automated truth-tellers (tests, checkers, formatters) that can tell your agent "no, not yet" without you in the room. This is the deepest lever in the chapter, because of one compounding fact: agents with good harnesses get better results from the same model.

What you will learn

• Understand why a harness multiplies agent quality — the self-correction economics.
• Build a starter harness for any project type, both lanes.
• Direct the agent to build and extend its own harness — tests-with-the-work as standard practice.

Builder principle

A deterministic check can repeat the condition it encodes. It still needs maintenance, relevant coverage, and human review of what the condition omits.

The economics of self-correction

Replay the agentic loop with and without a harness:

Without: act → "looks right" → report done → you find the breakage → explain it back → agent re-gathers your explanation → fix → repeat. Each defect costs a full round-trip through the scarcest resource in the system: your attention.

With: act → harness says FAIL: contact link broken → agent reads, fixes, re-runs → PASS → report done, with receipts. The defect died in-loop, seconds after birth, at zero human cost.

Same model, same task — radically different outcomes, and the gap widens with task size. This is the concrete mechanics behind a claim the course has made since 1.2: the harness is half the agent. Your model is rented; your harness is owned — it's CLAUDE.md's sibling in the "context quality" equation of 5.1, on the verify side instead of the gather side.

What goes in a harness

Three tiers, in order of construction:

Tier 1 — Does it work? The mechanical basics: does it parse/build/load? Broken links? Missing files? For a website: an HTML validity check + a link checker. For a Python tool: does it import and run its smoke test? Cheap, fast, catches the embarrassing class of defect entirely.

Tier 2 — Does it do the right thing? Tests that encode your done-means clauses (4.4, mechanized at last): "the contact form has all three fields," "the price calculation matches these five known cases," "no page scrolls horizontally at 375px" (Playwright from 8.3 makes even that testable — connections feeding the harness; everything composes). This tier is where your standards stop living in your head.

Tier 3 — Does it stay consistent? Formatters and linters — the style-matching rules from CLAUDE.md, enforced mechanically. This tier also quietly saves context: a formatter that fixes style automatically means style instructions can shrink out of CLAUDE.md. Mechanism eating discipline, again.

Build it with the agent — then make it standard

The harness, like the hooks, is agent-built under your direction:

Build a validation harness for this project as scripts/check.sh:
1) HTML validity for index.html, 2) all internal links resolve,
3) all image files referenced actually exist, 4) [your top done-means
clause, mechanized].
Run it, show me it passing, then break something deliberately and
show me it failing with a CLEAR message — the failure text is what
you'll be reading later, so make it tell you exactly what and where.

Two design points hiding in that brief. The break-it demonstration — a check you've never seen fail is unverified mechanism (9.2's rule, applied to the checks themselves). And the clear failure message — harness output is context the agent consumes (5.1 to the last); FAIL: footer link → pricing.html (file not found) feeds a one-turn fix, while Error 1 feeds a guessing spiral.

Then the standing order, into CLAUDE.md:

## Validation
- scripts/check.sh must pass before any commit.
- New features come WITH their check: any new done-means clause
  gets mechanized into the harness as part of the work, not after.

That second line is the compounding clause — the harness now grows with the project, each feature leaving behind its own permanent reviewer. Wire check.sh into your PostToolUse hook from 9.2 and the whole thing closes: standards encoded (9.3) + fired on every seam (9.2) + no memory required (9.1). The chapter's machine, assembled.

🌱 No-code lane⚙️ Engineer lane

You design the checks; the agent implements them — tier 2 especially is pure you: those are your done-means clauses, and you've been writing them since 4.4. Genuinely new superpower unlocked here: before, you could only verify by looking; now your standards check themselves while you're at lunch. Start with tier 1 today (fifteen minutes), add one tier-2 check per week from real defects you catch — a harness grown from your project's actual failure history beats any template.

You have a harness — CI, tests, linters. The agent-era upgrades: speed (the agent should run the relevant slice in seconds, in-loop — a 20-minute suite is a human cadence harness; carve a fast lane); failure-message quality (re-read your test output as context for a model — assertion messages that state expected/actual/where pay off immediately); and test-with-the-work as enforced norm (the agent writes the failing test first when fixing bugs — 6.3's executable reproduction — and ships features with coverage, checked by the hook, not the reviewer's memory). Your CI was built for humans at human speed; your harness now serves a worker that can consult it every thirty seconds. Feed it accordingly.

Try it now

1. Build tier 1 for your main project via the brief above — break-it demo included.
2. Mechanize your single most important done-means clause as the first tier-2 check.
3. Add the Validation section to CLAUDE.md, compounding clause and all; wire the harness into your after-edit hook.
4. The payoff experiment: give the agent a task that will trip a check, and watch — without intervening — as it hits the failure, reads it, and self-corrects. Journal what that felt like. (Most people report something like watching the training wheels come off — the system caught it, not them.)

Check your understanding

• Walk both defect timelines — harness and no harness. Where does the round-trip cost land in each?
• Name the three tiers and what question each answers. Which one encodes your standards specifically?
• Why do failure messages deserve design attention? (Two lessons converge on the answer.)
• What does the compounding clause do to the harness over the project's life?