The Org Harness. I had a CLAUDE.md that told the agent… | by Ian Johnson | Jun, 2026 | Towards AISitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Towards AI

We build Enterprise AI. We teach what we learn. Join 100K+ AI practitioners on Towards AI Academy. Free: 6-day Agentic AI Engineering Email Guide: https://email-course.towardsai.net/

The Org Harness

Ian Johnson

9 min read·<br>Just now

Listen

Share

I had a CLAUDE.md that told the agent how to write Laravel migrations. It said which column types we prefer, when to use a foreign key constraint, how to name the file, how to write the down step. It was a good CLAUDE.md. It said nothing about how a migration becomes work to do.<br>Where did the task come from? Who decided it was worth doing? Who said it was finished? The CLAUDE.md had no answers, because those questions live one layer out.<br>That phrase — one layer out — is the whole post. There’s a harness around the project harness. I want to name it.<br>What the project harness does<br>Most teams who pick up Claude Code build the same thing first. A root CLAUDE.md describing how to write code in this repo. A .claude/rules/ directory with topic-scoped rules. A .claude/skills/ directory with reusable procedures. Some hooks in settings.json. Maybe a few custom slash commands. That’s the project harness — the innermost layer of agent context. It governs how the agent behaves on whatever task is in front of it.<br>The reach of the project harness is intentionally narrow. It assumes a task has arrived already shaped. It assumes someone — human or otherwise — will check the result. Those decisions sit outside its window. The agent inside the project harness can see its rules, the task, and the codebase. Past that the view runs out, the same way a function inside a closure can’t reach the surrounding scope unless something hands it a reference.<br>That’s fine. The project harness shouldn’t try to do those jobs. It would get bloated and brittle if it did. The agent doesn’t need to know how the work was scored or who approved it — it needs to know how to write a migration in this repo.<br>For a small team running a few tasks a week, the project harness is plenty. A human is doing the outer work in their head: deciding what to pick up, framing the brief in a chat message, eyeballing the PR. The outer work is informal but real. It just hasn’t been written down.<br>The informal version breaks in predictable ways once load increases. Briefs given in chat drift from one teammate to another. Acceptance gets argued after the work is done because nobody wrote down what “done” meant before it started. Two agents start the same task because no one tracked who picked it up. A change ships that depends on a sibling change that hasn’t merged yet, and main goes red. These aren’t bugs in the project harness. The project harness was doing its job. The bugs are in the missing layer around it.<br>What the outer layer does<br>The outer layer earns its keep when the informal version stops scaling. When you have many contracts in flight. When more than one person is dispatching work. When you want consistency in how briefs get framed and how completion gets verified. When you’d like to swap providers — issue trackers, code hosts, notification channels — without rewriting your commands.<br>The outer layer is the delivery harness. It holds the things the project harness can’t see:<br>A backlog of signals and their scores.<br>Intent contracts as the unit of work — not tickets, not stories.*<br>Status transitions across the lifecycle of each contract.<br>Human touchpoints: when a person looks in, and when they don’t.<br>Merge gates and post-merge CI verification.<br>Bridge artifacts (contracts, completions, interrupts) that carry information across the boundary.<br>* Note: These do not have to be backed by tickets, but should be backed by a single source of truth. If that happens to be a ticketing system, then it’s just the implementation. The same is true if it’s just a collection of markdown files.

The four-phase shape I’ve been running looks like:<br>Discover, Define, Dispatch, Verify<br>Discover captures and scores signals. Define turns an approved signal into a contract with falsifiable acceptance. Dispatch hands the approved contract to an executor. Verify compares the result to the acceptance and closes the contract. Three human touchpoints sit along the lifecycle: a seed review when a signal enters the backlog, a contract approval before dispatch, a completion review after execution. Everything else is automated or self-directed. That’s the spine of the outer layer.<br>The outer layer doesn’t write code. It decides which task arrives at the project harness, with what brief, and what happens to what comes out.<br>Containment, not stacking<br>The relationship between the two layers is the thing I keep wanting to get right. Stacking implies the layers are peers, with one sitting on top of the other. Containment implies the outer layer wraps the inner one —...