HarnessEngineeringDemo

A runnable companion to the grey paper Harness Engineering: The Devil Is in Your Details.

The paper argues one thing: the model is the commodity you already pay a flat subscription for, and the harness is everything you build around it. This repo makes that physical. One tiny task, five rungs, and you watch the same job go from crashing to correct as each layer of harness gets added. Nothing here is bought. All of it is built.

Every harness piece is a native Claude Code surface: a CLAUDE.md, a slash command, a hook, a subagent, a project skill. Every one runs on a Claude subscription. None of it touches the metered API. That is the whole argument in miniature: the subscription is bought, the harness is built.

The task

Total revenue per customer from sales.csv. It sounds trivial. The file has four devils planted in it on purpose, the kind of details that make code "looks right, is wrong":

1. a customer named "Acme, Inc.", with a comma inside the quotes
2. money like 19.99, which drifts if you sum it as floating point
3. a UTF-8 BOM on line 1, which quietly renames the first column
4. a row reading " Acme, Inc. ", padded with spaces, that should dedupe with "Acme, Inc."

Any one of them is enough to hand you a confident, wrong number.

Setup once

You need Python 3.9 or newer. That is the only prerequisite.

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt  # pytest, ruff

The 60-second hook

Before you read another word, watch the ungoverned version fall over:

cd 00-no-harness
python3 revenue.py sales.csv

It does not print a total. It throws ValueError: too many values to unpack, because the very first customer has a comma inside quotes and the naive script split on it. That is the model with no harness. Now climb.

The climb

Each folder is standalone and has its own short README: what you'll see, the one command, the expected output. Walk them in order.

Rung	Adds	What you learn	Scale
00-no-harness	a prompt, nothing else	ungoverned, it crashes on real data	code
01-context	a CLAUDE.md of conventions	it runs, looks right, and is quietly wrong	code
02-spec	test_revenue.py, the four devils as tests	the spec catches what conventions missed	code
03-loop	a /verify command and a hook	the check runs itself, no babysitting	people
04-org	a review subagent and a shared skill	the judgment becomes the team's	org

The turn to watch is rung 01. Rung 00 fails loudly, so you know. Rung 01 succeeds quietly, so you don't. It prints Acme, Inc.: 30.00 when the answer is 30.10, and hides the missing dime in a second bucket named Acme, Inc.. Only the test at rung 02 catches it. That test is not clever. It is memory: this codebase already paid for that bug, and it refuses to pay twice.

Two ways to run everything

Without Claude, for free. python3 revenue.py sales.csv and pytest -q are plain Python. They prove the point objectively on any machine. Start here.

With your Claude subscription. Each rung's README ends with a "try it yourself" step: open Claude Code inside the folder and let the harness in that folder do the work. The CLAUDE.md, the /verify command, the hook, the reviewer, the skill, they all run on your subscription. You are not renting an API. You are driving a harness you own.

What it looks like to drive it

An illustrative session, condensed. The Python and pytest output is real; run it yourself and you will see the same. The Claude Code dialogue shows the shape of driving the harness, not a verbatim capture.

Rung 02, you specify and the spec corrects you:

$ claude                                    # inside 02-spec/, on your subscription

> Write revenue.py so test_revenue.py passes.

  Reading the spec and CLAUDE.md first.
  Writing revenue.py with the csv module, Decimal, and utf-8-sig.

  $ pytest -q
  FAILED test_whitespace_keys_dedupe
    " Acme, Inc. " was not folded into "Acme, Inc."

  The spec caught a missing normalization. Adding .strip() to the customer key.

  $ pytest -q
  5 passed in 0.08s

  Done. All five checks green.

The first attempt missed the whitespace devil. Nobody had to notice. The test did, and the agent fixed it before calling the work done.

Rung 03, the loop runs without you asking:

> /verify
  $ pytest -q       -> 5 passed
  $ ruff check .    -> All checks passed!
  Verified, both clean.

> Round the totals to whole dollars.
  [edits revenue.py]
  hook PostToolUse -> pytest -q
  FAILED test_totals_are_correct: expected Decimal("30.10"), got Decimal("30")

  The hook ran the spec the moment the file was saved. That change breaks the
  contract. Reverting.

The regression never reached you. The loop caught it at the keystroke.

Rung 04, the team's judgment is on call:

> Review my change to revenue.py before I merge.
  Delegating to the reviewer subagent.

  reviewer:
    1. quoted commas    handled (csv module, not str.split)
    2. money as Decimal handled
    3. UTF-8 BOM         handled (utf-8-sig)
    4. whitespace keys   handled (.strip)
    $ pytest -q -> 5 passed
    Verdict: safe to merge.

You did not have to remember the four devils. The reviewer did, because the team taught it once and it does not forget.

The point

Buy the model. Build the harness. The four devils in this repo are toys, but the shape is real: the details that decide whether your code is correct are specific to your data, your history, your team, and they were never for sale. The devil is in your details, and the details are yours.

---

Companion to the grey paper at emangini.com. Written to be cloned, run, and argued with.