The Machinery: A Production Playbook for Coding with AI Agents

How to wire the disciplines into a real system — the multi-agent, cross-substrate layer the general guides don't cover

By Alex Hinojosa and Claude

This is the companion to Your AI Coding Partner Will Tell You It's Done. Here's How to Actually Know. — the field guide lays out the disciplines (tool-agnostic; practice them anywhere, even a single chat window). This playbook is the machinery: how we turn each discipline into standing infrastructure in a system where multiple AI agents, on different model families, build and review each other's code all day under one human operator.

There are excellent general guides for getting good results from an AI coding tool — Anthropic publishes one for Claude Code, and you should read it. This is not that. This picks up where the single-human, single-agent guides stop: what changes when you run agents in production, in parallel, checking each other. That's where the interesting failure modes and the highest-leverage patterns live, and it's the part almost nobody writes down. We use Claude Code, so some specifics are Claude-Code-flavored; the shapes generalize to any capable agent runtime.

Every section names the field-guide discipline it implements — by title, not number, so the reference stays valid even if either doc is reordered (the exact reference-rot both pieces warn about).

1. Persistent project context: the memory file and @-imports

(Implements the discipline "A rule you only wrote down is not a control.")

The AI reads a single project file — for us, CLAUDE.md — at the start of every session. It holds what the AI can't infer from the code: the non-obvious build command, the branch convention, the "never do X" prohibitions, the gotchas. That file composes others with an @path/to/file import (@docs/git-instructions.md, @~/.claude/personal-overrides.md), so shared instructions live once and get pulled in where needed.

The hard-won lesson: keep it short. A bloated memory file is worse than a short one — the AI starts ignoring half of it and you can't tell which half. Our test for each line is would removing this cause a mistake? If not, cut it. And the deeper move: anything that must happen every time doesn't belong in an advisory file at all — it belongs in a hook (§6). That's the field guide's two-days-in-prose lesson made mechanical: a policy that only lived in the memory file turned out never to have been enforced — because prose is a suggestion; a hook is a control.

Multi-agent wrinkle: each agent boots from its own memory file, so its identity and lane are encoded there. Getting this wrong is its own failure mode — we once had two agents boot the same identity from the same file and quietly write over each other for three days. In a fleet, the memory file isn't just context; it's the thing that keeps agents from colliding.

2. On-demand procedures: skills

(Implements reproducibility — "identical procedure every time.")

A skill is a folder with a SKILL.md — a named, reusable procedure the AI loads only when it's relevant, rather than carrying it in context always. It's the counterweight to "keep the memory file short": the sometimes-relevant stuff (how to run a specific migration, cut a release, execute our evidence-verification routine) becomes a skill that loads on demand, invoked by a human typing /skill-name or by the AI recognizing the situation.

The payoff is reproducibility. "The AI remembers how we do releases" is unreliable; "the release procedure is a file the AI executes" is not. In a multi-agent system this compounds: a skill is a procedure every agent runs the same way, so consistency doesn't depend on each agent having independently learned it.

3. Durable work tracking: the task board + handoffs

(Implements "Know when it's too full to touch live systems" — context management.)

Two problems compound in long or multi-agent work: context fills up (so you must clear it), and work outlasts any single context window. We solve both with a persistent task board (a lightweight issue store outside any conversation) plus a handoff protocol. Before an agent clears context or ends a session with work in flight, it writes a short handoff — done / remaining / decisions / uncertainties — to a shared location. On wake, it reads its latest handoff first.

The board holds the what; the handoff holds the where I was and why. Together they make "clear your context aggressively" survivable — clearing costs nothing if the state was written down first. In a fleet, the same mechanism is how work moves between agents: one agent's handoff is another's starting point. The hallway between sessions is the memory.

4. The core loop: Builder writes the plan, Reviewer writes the prompts

(Implements four disciplines at once — "The thing that wrote the code cannot grade it," "Specificity collapses rounds," "Don't chase every finding," and "Cap the rounds. Then change the game." The heart of the whole thing.)

This is the workflow that cut our review cycles the most. Two roles: a Builder (writes code) and a Reviewer we treat as a Head of Engineering (reviews, and crucially, directs). They run on different model families, so the reviewer isn't grading its own reasoning (a different mind checks the work).

1. Builder writes a plan first — before any code. Not prose about the code; a spec-grade plan: the files and interfaces it will touch, what's explicitly out of scope, the independent pieces (so they can be built and verified separately), and — the part people skip — it ends with an end-to-end check that proves the feature works. A plan that ends in "here's how you'll know it's done" is a plan the reviewer can hold the result against.

2. The plan clears a review gate before implementation. This catches "you're about to solve the wrong problem" while it costs one paragraph, not a day of code. The reviewer accepts the plan or sends specific corrections to it.

3. Builder implements against the accepted plan, optionally fanning out sub-agents for genuinely independent pieces (§5), then runs one fresh-context self-review over the whole diff and fixes or explicitly waives every finding — no silent skips.

4. The Builder submits a packet: the plan, plus the self-review's findings and what it did about each. A packet missing either is bounced automatically — the enforcement is a check, not a polite request.

5. The Reviewer does NOT hand back a list of concerns. This is the pivotal move. Instead of "the error handling around token refresh looks incomplete" — which sends the Builder off to interpret, guess, and often guess wrong (another round) — the Reviewer writes a specific, self-contained fix-prompt per item: the named file, the exact change, the check that proves it. The Builder executes the prompt; it does not re-derive it.

   Before (a round of ping-pong): "The reproduction gate is failing; figure out why and fix it."
   After (converges in one pass): "In serve.py, load_accepted_model() fails its reproduction check because the input corpus isn't pinned. Pin it to the commit recorded in accepted_metrics.json, re-run the gate on the pinned corpus, and confirm it passes there and fails on a one-row mutation. Don't loosen the tolerance."

   The gap between those two prompts is a review round. We erased it by making the reviewer responsible for closing it — the change behind the field guide's "six rounds became one hour."

6. Scoped review with a residual register. Each finding is blocking (a correctness defect or a stated requirement) or optional (style, hardening beyond spec). Only blocking gates acceptance — chasing every finding leads to over-engineering (the "don't chase every finding" discipline). But optional never means silently dropped: each is listed with what closing it gains, what leaving it open costs, and the exact condition under which the risk bites (or "cosmetic — never bites"). Anything with real residual risk becomes a tracked ticket. This makes every deferral conscious and auditable, and stops a reviewer from hiding a genuine gap under the word "optional." One override: a live security exposure is always blocking, never optional.

7. A round cap. If review reaches a third round, something structural is wrong and more lists won't fix it — so the reviewer switches from listing findings to sending the actual fix (applied verbatim) or diagnosing the root cause of why fixes keep spawning findings.

5. Parallelism and adversarial verification: sub-agents and orchestration mode

(Implements "The thing that wrote the code cannot grade it" and "Expect it to say 'done' too early.")

For a task with genuinely independent pieces, a lead agent can decompose it, spin up parallel sub-agents each in its own fresh context, then integrate the results. The critical addition — the thing that separates this from "just go faster" — is an adversarial verification step: before the work is called done, a separate sub-agent, seeing only the diff and the criteria, tries to refute the result. The agent that did the work is never the one that certifies it.

Claude Code exposes a session-scoped mode for exactly this shape — auto-decomposition, parallel workers, adversarial checks before delivery (you may see it called an "ultra" orchestration mode). Whether you use a built-in mode or wire it by hand, the pattern is the same: fan out to go fast, then have a fresh, adversarial reviewer try to break the result before you trust it.

The twist worth stealing — cross-substrate review. Our adversarial reviewers run on different model families than the builder. Same-model review is partly blind to same-model mistakes; a different model on the same diff catches a different class of error. This is not a nice-to-have — it's the mechanism behind the field guide's credential-store story: the second model that caught the world-readable store the first had walked past three times was a different substrate, and that is exactly why it saw what the first could not. If you can afford to run your reviewer on a different model than your builder, do it — it is the single highest-value structural choice we've made.

6. Deterministic guards: hooks

(Implements "Give it a check that can fail" and "A rule you only wrote down is not a control.")

A hook is a script that runs automatically at a fixed point — before a tool executes, before a commit, after an edit. Unlike a memory-file instruction (advisory, sometimes-followed), a hook is deterministic: it happens every time, zero exceptions. This is how you make "a rule you only wrote down isn't a control" untrue. We run hooks that scan every file write for secret patterns and block on a hit, that refuse writes to protected paths, and that block a session from ending until a required check passes. If a thing must happen, it's a hook; if it's a preference, it's a memory-file line. Knowing which is which is half the battle — and it's the layer that survives even when an agent runs with permissions relaxed, because hooks fire regardless of permission mode.

7. Fresh, isolated context: sub-agents for investigation

(Implements "The thing that wrote the code cannot grade it" and "Know when it's too full to touch live systems.")

When the AI must explore a large codebase to answer a question — reading dozens of files — doing it in your main conversation fills your main context with files you'll never need again. Delegating to a sub-agent solves two problems at once: the exploration happens in a separate context that's thrown away (keeping your main session clean — the context discipline), and when you use it for review, the sub-agent's fresh, isolated context is exactly the unbiased second look fresh eyes call for. "Use a sub-agent to investigate X and report back" is one of the highest-leverage sentences you can say.

What actually makes this a system and not a pile of tips

Everything above answers one question the field guide keeps asking: how do you make a discipline stick when the AI is fast, confident, and forgetful? You stop relying on the AI to remember it and build it into the machine — a skill it loads, a hook that fires, a reviewer whose job is to be specific, a plan it must write first, a check that can fail.

But the multi-agent layer adds a second answer the single-agent guides can't: you stop relying on any one mind — human or model — to be the whole verification loop. The builder is fast; a different model reviews it. The reviewer is specific; a hook enforces what the reviewer can't watch for. Context fills up; the board and the handoff carry the state across the gap. No single component is trusted to be reliable, because none of them is. The reliability is a property of the loop, not of any agent in it.

That's the whole trick, and it's why it scales: you're not making the AI more careful. You're building a system where careless is caught.