Feature Library
Playbook

Many agents, one codebase

Running several AI agents on one repository at the same time without them colliding: how to shape the code so they can’t, what goes in their brief, and how to check what comes back.

Updated 16 November 2026 · checked with Claude Code, Nov 2026

Seventeen of this library's entries were built by seventeen agents, up to thirteen of them at once, in one working copy. None of them touched another's files, and the whole batch went in as one clean commit. That was not luck: it came from how the code is laid out, one brief they all read, and a coordinating session that owned everything shared and checked everything that came back. This playbook is that setup, and what went wrong on the way.

Before you start

Run through this before you hand work to more than one agent.

  • (default) The work splits into pieces that each live in their own folder, or in files no other piece touches.
  • (default) No piece has to edit a shared list (an index, a route table, a registry): the code discovers pieces from their folders instead.
  • (default) The contract is fixed: the types, the API between the pieces, the folder layout and what "done" means.
  • (default) Every shared file has one owner, the coordinating session, and agents are told not to edit it.
  • (default) One brief, kept as a file, says what to read, the rules, how to check the work and how to report.
  • (default) A small first batch goes out before the rest, and what it teaches goes into the brief.
  • (default) Anything that needs the whole machine (measuring, capturing every preview) waits until every agent is done.
  • (default) Each report is checked against the work itself: the diff, the tests, the build and how it looks.

Shape the code so agents can't collide

The strongest protection is a codebase where parallel work never meets in the same file. Rules in a brief help; a layout that makes collisions impossible helps more.

Here every entry is a folder, and the site finds the folders itself. Adding an entry edits nothing outside it:

// Every entry is a folder under entries/: the site finds them here, no list to keep.
const metas = import.meta.glob<EntryMeta>('/entries/*/entry.ts', { eager: true, import: 'default' });

Look for the places where every new piece would otherwise have to add a line, and remove them:

A shared list……becomes
an index file importing every modulediscovery from folders (import.meta.glob, a directory scan)
a route tableroutes derived from the folder or the metadata
one big stylesheetstyles in each folder, every class under the folder's own prefix
a dependency list everyone adds toa rule: no new packages without the owner

Then let tests hold the line, so a piece that strays fails before anyone has to notice. This library's tests fail if an entry's code imports anything but three.js and its own files:

// Inside the module only relative imports that stay in the folder, or three.
if (spec.startsWith('.')) expect(resolved.startsWith(moduleDir), `${file} leaves the module`).toBe(true);
else expect(spec === 'three' || spec.startsWith('three/'), `${file} imports ${spec}`).toBe(true);

Fix the contract first

Agents working in parallel can't negotiate with each other. Whatever they share has to be settled before they start: the types, the API between the pieces, the folder layout and what a finished piece contains.

Before the seventeen agents started, two categories were added to the entry schema ("Data & layout", "Systems & tooling"). Left open, each agent would have stretched the old ones in its own direction, or edited the schema itself. A contract that changes mid-flight means every agent redoes its work against the new one.

The rule for agents: if your piece needs a change outside your folder, stop and say so in your report. Don't make it.

One owner for shared files

Some files belong to everyone: the schema, the site's styles, package.json, the tests, the docs. Give them to one owner, the coordinating session, and have every agent report what it needs there instead of changing it.

It pays off quickly. Two agents separately found that entry pages scrolled sideways on phones, two more that the hint over a demo covered their toolbars, and another that a demo kept running after its page closed. All three bugs were in site code. Each was fixed once, by the owner, instead of several agents writing different fixes to one stylesheet at the same moment.

One brief, improved between batches

Every agent read the same brief file first. Its own prompt then added only what was specific to it: the entry's id, its source files and what its demo should show. One brief keeps seventeen pieces consistent, and it gives you a single place to fix a mistake for everyone.

A brief that worked had five parts:

# Building one <piece>: the shared brief

## Read first
The README, the contract (types, API), the tests, and two finished pieces as models.

## What to make
The files of one piece, what each holds, and the conventions to match.

## Rules
Write only inside <your folder>. No new packages. Shared files belong to the owner:
if you need a change there, stop and report it. Credit what isn't yours.

## Check before you report
Typecheck, the tests for your piece, and see it working: in a tab of your own,
at desktop and phone width.

## Report (under 300 words)
What you built, its sources, what you couldn't check, anything needed outside your folder.

The report section matters more than it looks. Asking for "what you couldn't check" is what made the agents say plainly when a screenshot had failed or a check was done by script, so you know where to look yourself.

Start small, then fan out

Send a first batch, read what comes back, and fold the lessons into the brief before the rest go out. Here, six went first, and their first two reports were enough to add four lines to the brief before the other eleven started:

  • Prefix every class name: the site's global .card and .empty were overriding the agents' own.
  • The browser pane is often hidden, and a hidden page draws no frames, so a frozen animation isn't a bug.
  • Other agents' saves will reload your page: reload and carry on.
  • Keep code lines in guides short.

Sharing one working copy has costs of its own. These all came up:

What you seeWhyWhat to do
Your page reloads in the middle of a testAnother agent saved a file the dev server watchesExpect it; check in short steps, or by script
Type errors in files you never touchedAnother agent is halfway through writing themCheck only your own files until everyone is done
Animations don't move in screenshotsThe browser pane is hidden, so it draws no framesStep frames with screenshots, or read the page's state
No browser tab left to openEarlier agents left theirs openClose your tab when you're done
GPU timings jump aroundOther agents' demos, or a hot laptopMeasure everything at the end, in one sitting

Check the work, not the report

The reports were honest, but each describes what its agent checked, and an agent checks less than it thinks. Two real bugs got past seventeen careful reports, and a third got past the owner's own:

  1. A chart's draw-in animation restarted every few frames during measuring, so its preview caught the charts empty.
  2. One rule of invalid CSS broke the production build. Every agent had checked its work on the dev server, which is forgiving; none had run the build.
  3. The owner's own fix to the infinite canvas sent its measured run into an empty part of the board, so its preview showed nothing at all.

All three were found the same way: by looking at every result side by side, not by reading about it.

So when the last agent reports, the owner runs the whole set, on everything at once:

  • (default) Typecheck the whole repository, not file by file.
  • (default) Run every test.
  • (default) Run the production build.
  • (default) Measure everything in one sitting, so the numbers compare.
  • (default) Look at every result yourself: a preview of each piece, side by side.
  • (always) Read each piece's credits and source notes, because code copied without its credit breaks its licence.

Generated content: stage, check, then install

When an agent's work is generated files that land in a shared place (content definitions, a registry, a defaults file), don't let the generator write there directly. Split it into three steps, each one run on its own:

  1. Generate into a staging folder inside the agent's own area, cleared first, all files written in one go.
  2. Validate read-only against the real code that will consume them: the live content plus the staged files, loaded through the app's own assembler and validators, not a copy of their rules. Check that everything the files name exists in the built assets, and that adding them changes nothing about anything already there.
  3. Install with a separate flag, which only copies the staged files into place.

A failing check then costs nothing: the shared folder never saw the files. And the check proves what matters, which is that the real assembler accepts them, rather than that the generator thinks it wrote them right.

Tried on the game. A new vehicle's content (one vehicle and 81 parts over 48 mounts) is generated from the Blender builder's report into a staging folder. A validator loads it beside the live content through the game's own assembler and workshop checks, confirms every node it names exists in both exported models, and fails if any existing vehicle's hidden parts, mass or engine force change. Only then does --install copy it into the content folder and the factory defaults.

When one working copy isn't enough

All of this assumes the pieces don't need the same files. When they do (two features that both change the router, say), give each agent its own worktree and branch, and merge them one at a time afterwards. Branching and forking has the worked examples.

As of November 2026, in Claude Code: agents started with the Agent tool run in the background and report back when done. An agent can be given its own git worktree (isolation: "worktree"), or be a fork that inherits the whole conversation instead of a fresh brief. A fresh agent with a short brief is cheaper than a fork, and a better test of whether the brief is complete.