Harness Manual — 02 Building It by Hand

A constitution document, an agent file, a skill file, a wiring map and a checkpoint. The actual sequence for building a minimal harness with five text files, retaining only the structure verified across nine workshops.

§ 00 · File one — a sixty-line constitution

Create a file named CLAUDE.md at the repository root. Files with this name load automatically whenever a session opens: the convention that forms the harness’s cornerstone. Start with just three things. Five lines on what the project is. A few absolute prohibitions, such as “Do not report unverified work as complete” and “Do not push directly to the main branch.” Then the validation commands: how to run tests and check the build.

Start around sixty lines and stay near that length. The reason is simple: the longer the rulebook, the less attention each rule receives. Published measurements are chilling. With ten rules, most are followed; with fifty, half are ignored; with a hundred, the machine cannot tell what matters. Beyond three hundred lines it starts selectively ignoring rules. The workshop observations confirm this. When one constitution exceeded five hundred lines and rule violations increased, its workshop cut it to one hundred and fifty and moved the rest to a separate knowledge folder. The largest workshop keeps its constitution at seventy-three lines and even has a sensor warn before a commit if the line limit is exceeded. Keep only the map in the constitution; put details behind links.

Avoid one trap from the outset: do not write counts in documents. Numbers such as “seven sensors” or “twenty-four tests” start decaying the moment they are written, because files multiply while documents remain unchanged. Two remedies were observed. Write the command that counts instead of the number—“measure the count with ls”—or attach a script that overwrites the documented number with the measured value immediately before a commit. The principle is the same: make the document point to reality instead of claiming what reality is.

§ 01 · File two — the agent

Create .claude/agents/ and put one Markdown file per worker inside. At the very top, within frontmatter enclosed by three dashes (---), write four lines. name: the worker’s name, such as verifier. description: when to call it, such as “When validating a completion claim. Judge only; do not edit code.” tools: the tools it receives, such as Read, Bash and Grep, deliberately excluding editing tools. model: the model to use, covered in Part 05.

The body follows almost the same structure across the nine workshops. At the top is a block of absolute constraints: prohibitions and duties marked at three levels—required, recommended and optional. Next come the role description and the list of canonical documents that must be read before working. At the bottom is another checkpoint just before submission: “Did you claim completion without measurement?” “Did you attach the original output?” These are double anchors, placing the same constraint at both ends. They reflect an observation across several workshops: in long documents, the machine follows the beginning and end most reliably.

Which worker should you create first? The observations give a clear answer: start with a validator. Before a worker that implements well, you need one that measures for you whether implementation actually happened. Once a dedicated inspector without editing tools exists, “It’s all done” becomes “It passed the inspector.” That difference is where a harness begins.

§ 02 · File three — the skill

Create a folder under .claude/skills/ and place SKILL.md inside. Two frontmatter lines are enough to begin: name and description. State a specific activation condition in description. Some workshops add an array of trigger keywords: roughly twenty phrases such as “Complete,” “Everything passed” and “No problems,” so the skill intervenes just as those words are about to appear.

The first skill is almost predetermined: the completion gate. Write this in the body: before declaring completion, actually run (1) the type check, (2) tests and (3) the build. Attach each command’s raw output to the report. Add three prohibitions: no completion claims without measurement; no claiming everything passed after checking only part; no passing off a previous session’s results as current evidence. Those lines were fixed in place after actual incidents in several workshops, and their effect is measurable. In the benchmark turnaround mentioned earlier, this single pre-submission self-check pattern made the largest contribution.

Finally, put a reporting template in the skill. Four fields suffice: verdict, commands run, raw output and remaining problems. A fixed reporting format makes evasion harder. Either a blank is filled or the blank itself becomes visible.

§ 03 · Files four and five — the wiring map and checkpoint

The fourth file is the wiring map, .claude/settings.json. It connects a moment to the script that should run then. The most common minimal wiring observed has three strands. Session start: a script checking whether memory is current. Immediately after a file edit: a script quietly running the type checker. Session end: a script warning if there are commits today but no record. Put the scripts themselves in .claude/scripts/; have the machine write them using Part 03’s method.

One rule for wiring: hooks generally do not block. The overwhelming majority of observed hook scripts end with “pass no matter what”—exit 0—because a defect in the hook must not halt all work. Their real value lies elsewhere. A chat request saying “Don’t” is the weakest restriction, one the machine can ignore; a hook operates regardless of the machine’s intent, making it the most reliable restriction. Ordinary hooks whisper. The fifth file bites.

The fifth file is the real checkpoint. Create a shell script named pre-push in .githooks/, following Git’s convention for automatic execution immediately before pushing to a remote repository. It runs the three sensor stages—type check, tests and build—in sequence, rejecting the push itself with exit code 1 if any stage fails. Enable it with one terminal command: git config core.hooksPath .githooks. The user runs this once personally. From that moment, deployment with broken tests becomes structurally impossible. It is not a question of the machine’s laziness; the door is locked.

Read this note at sass.studio.