# The Org Harness > Source: > Published: 2026-06-15 23:31:00+00:00 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. 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. That phrase — *one layer out* — is the whole post. There’s a harness around the project harness. I want to name it. 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. 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. 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. 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. 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. 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. The outer layer is the delivery harness. It holds the things the project harness can’t see: * 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: *Discover, Define, Dispatch, Verify* **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. 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. 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 — sets the boundary, defines what gets in, decides what comes out. The inner layer doesn’t know it’s inside anything. From the agent’s perspective, the project harness is just “the rules.” There’s no upward reference. The outer layer holds the closure; the closure can’t see its own holder. The shape: *Concentric. The agent sits in the innermost ring with the project’s rules. The delivery harness wraps that ring and handles everything about work flow. A further layer can wrap the delivery harness when an organization has many of them.* The diagram matters because the wrong picture leads to the wrong design. If you draw two boxes side by side, you start asking how they communicate as peers, and you end up building a bus or a sync protocol between them. If you draw them concentric, you ask a different question: what does the outer layer hand inward, and what does the inner layer emit outward? That’s a much smaller surface. The bridge artifact is the contract. The outer layer produces it. The inner layer consumes it. The seam is clean because the artifact is the only thing that crosses. Here’s a contract going through both layers. Project key PROJ, contract id IC-PROJ-42, code repo org/some-app. A signal arrives in the issue tracker. That’s the outer layer. The signal is a task or a bug, captured with enough context to be reviewed but not yet shaped. A human gives it a quick read and decides it deserves drafting. /idd-draft reads the signal and writes a contract into the issue description. The contract has sections — outcome, scope in, scope out, acceptance criteria, open questions, links. Still outer layer. Still no code touched. The human reviews the contract. If anything’s vague, it goes back. If the acceptance criteria aren’t falsifiable, it goes back. If scope is missing, it goes back. When it reads clean, the human approves it. That’s touchpoint two. /idd-dispatch is where the layers meet. It loads the contract AND the project’s CLAUDE.md into the executor’s working context. From this point until completion, the executor is running inside the project harness. The project’s rules govern: scope discipline, comment style, refactoring restraint, test posture, anything that’s true about *this* codebase. The executor does the work. It branches from main, edits the named files, writes tests, opens a PR. If it hits ambiguity, it files an interrupt — a small artifact that surfaces a decision to the human and pauses execution. One question per interrupt. The interrupt is still an outer-layer artifact; the inner layer produces it but the outer layer carries it to a human. When the work is done, the executor writes a completion report — acceptance check per condition, interrupts list, change summary. That’s the second bridge artifact across the seam. The outer layer takes the completion and runs the rest of the lifecycle. It watches CI. It posts a notification to the human reviewer. It moves the status forward. It does none of this from inside the agent’s context window — the agent emitted the report and moved on. The human reviews the completion. That’s touchpoint three. If it’s accepted, the contract closes and the status transitions to whatever the outer layer calls “released to staging.” If it’s rejected, the contract stays as-is — failed contracts don’t get retconned — and a new signal opens to address whatever went wrong. That’s the whole flow. The inner layer ran for one phase, framed by the outer layer on both sides. If you can’t decide where a rule belongs, ask one question: what would change it? Things that change with the tech stack belong in the inner layer. Tone-and-style rules for code. Refactoring discipline. Test-writing posture. Code-review etiquette. The “always run the type checker before committing” hook. The “match the existing style even if you’d do it differently” rule. The migration column conventions I started with. Switch from Laravel to Rails and most of this changes. Things that change with the delivery model belong in the outer layer. Backlog scoring. Contract sections. Touchpoint sequencing. Merge gates. Post-merge CI verification. Status transitions. Switch from Scrum to Kanban to Shape Up and these change; the migration conventions don’t. A useful litmus: would this rule survive a change of tech stack? Then it’s outer. Would this rule survive a change of process? Then it’s inner. The rules that survive both are candidates for a further layer outward — an org or personal harness that lives above the delivery harness. The outer layer needs ports and adapters the way any system with pluggable providers does. The delivery harness I run has a signal-source port (an issue tracker), a contract-store port (where the contract artifact lives), a code-host port (where the PR opens), and a notification port (how humans get pinged). Each port has a spec; each adapter is named in a config file. Swap the issue tracker provider and the slash commands don’t change — the adapter under the port does. Same containment principle, one ring further in: ports define the boundary, adapters fill it. There’s no reason to stop at two layers. An organizational harness can contain multiple delivery harnesses across teams. The backend team has one. The mobile team has another. Both sit inside an org-level harness that holds shared security baselines, the common compliance gates, the design-system MCP server, the shared rule library. Each delivery harness loads what it needs from the layer outside; it can’t reach over to the other team’s harness directly. A personal harness wraps everything you do. Your keybindings. Your global ~/.claude/CLAUDE.md. Your prompts. Your agent definitions. Your shell aliases. That layer travels with you across orgs. When you switch jobs, the personal harness is what comes with; the org harness gets left behind. The pattern repeats at every boundary. Load context inward at the seam. Receive emissions outward through bridge artifacts. Don’t let layers reach across — make the boundary explicit and the artifacts named. The shape stays an onion no matter how many rings you add. A different post for a different day. The point here is that the project harness isn’t the whole thing — and naming the layer that contains it is the first move toward building it deliberately. A few concrete actions if any of this resonates. Read your current CLAUDE.md end to end and ask, for each section: is this rule about *how to do the task*, or about *which task to do and how it flows*? Most teams have a few paragraphs of the latter mixed in with the former. Move them out. Even if “out” is just a separate doc for now, the separation is the start of the seam. Pick one decision your team re-makes per ticket — what’s in scope, what counts as done, who signs off — and move it into a structured artifact one layer out. A contract template is a fine first version. You don’t need the four-phase workflow to get value from naming the brief. Name your human touchpoints. Three is a good target. More than five and you’re approval-heavy; fewer than two and you’re under-supervised. The touchpoints don’t need to be slick; they need to be deliberate. If you can articulate what arrives at your project harness and what it emits — what crosses the seam in each direction — you’ve already drawn the boundary. Make it explicit. Write it down. Once the seam has a name, the outer layer has somewhere to grow. The project harness is where most of us started. It’s worth knowing there’s a layer around it, and it’s worth asking whether you’re ready to build that layer yet. For a small team, the answer might be not yet. For a team with more than a handful of contracts in flight at once, the answer is probably already overdue. [The Org Harness](https://pub.towardsai.net/the-org-harness-edef5844ba10) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.