Coordinating coding agents in a large codebase

Over about five weeks, around 90 Claude Code worker sessions produced more than 60 merged pull requests. I sent about 200 messages, nearly all to the same thread. A typical message from me was around 15 words. That thread turned the decisions we made into briefs that typically ran to a few thousand characters, followed up with the workers and checked their changes.

I call that thread the ringleader. I asked it to work through an agreed plan in phases and wait for prerequisites to merge before starting dependent work. Some workers implemented changes. Others reviewed code, tested behaviour or investigated failures. Transcript estimates put about nine-tenths of the recorded model output in the worker sessions. I’ve rounded the figures because they come from a work codebase.

I turned what I learned into a Claude Code skill and first used it on a navigation refactor. Read the ringleader skill.

Split the work where ownership is clear

The ringleader looks for tasks with clear file ownership and a result it can verify. If two workers will use the same function or response shape, their briefs need to specify the same interface. When one task defines that interface, its implementation can land first and give the dependent worker something concrete to build against.

For work that will land as separate pull requests, the ringleader starts separate Claude Code sessions. Each can use its own Git worktree, a separate checkout in which it can edit and test its branch. When the result belongs in a single pull request, subagents can share a worktree if each has a distinct set of files to edit.

Put the decisions in the brief

The skill has three rules about what workers know, when they can respond and how the ringleader checks their work.

A worker raised a blocking question, waited roughly ten minutes and then proceeded on its own. By the time the answer reached it, the work had finished. It’s the reason I put blocking decisions in the brief.

You cannot talk to a busy worker.

The brief specifies which decisions are settled and which uncertainties require the worker to stop and report back. It also has to carry the context the worker needs to get started.

A worker knows only its brief.

For the navigation refactor, the ringleader’s first implementation brief included the goal, the agreed phases, decisions from the planning discussion, relevant file paths and the repository rules.

The brief needs to distinguish what the ringleader has verified from what it suspects. If it suspects two callers use the same helper, it asks the worker to trace both callers and report where they lead. An implementation brief ends by asking for the commit or pull request, the checks the worker ran and any unresolved assumptions. An investigation report identifies the files inspected, the evidence found and any decision needed from the parent.

Check the changes together

Two sibling pull requests merged cleanly as text and failed type checking together. One removed an export the other used. The merge queue caught the failure.

A worker’s report is a claim, not proof.

The ringleader uses each report to locate the change and see what the worker checked. It reads the diff, reruns the relevant checks and verifies dependencies between tasks against the combined code. When the change affects a user flow, it exercises that flow too.

In one hands-on check, the ringleader found that an action could submit twice and that keyboard focus was handled incorrectly. Several agents had already worked on the change, and hundreds of tests had passed. The defects surfaced when the ringleader exercised the interaction.

What delegation costs

Four workers once installed dependencies and built in parallel. They filled the disk in about an hour and stopped the local container runtime. The ringleader now checks free disk space before starting workers in parallel. Each brief sets a minimum amount of free space. The worker cleans up build output as it goes and stops if free space drops below that floor.

A fresh worker also spends time reading. In the sessions I examined, a cold start could take around half an hour and use several hundred thousand tokens. A follow-up in an existing worker took a fraction of that time in one comparison. I haven’t measured the total cost or elapsed time against doing the same project in one thread.

The skill defaults to a worker model one tier below the ringleader. In the larger project, the parent and nearly all the workers ran on Opus. I haven’t tested whether cheaper workers hold up at that scale.

I keep small edits in the parent thread when briefing a worker and checking its result would take longer than making the change. I also keep tightly coupled edits together while their interface is still taking shape.

Decide what you can check before delegating

When I plan a phase, I start with what the ringleader will check when the work comes back. The worker can show that its branch builds. The ringleader needs to show that it still builds with the other changes, and that the affected flow works. If I can describe those checks before sending the brief, I can hand off the implementation and use one conversation to decide whether the project is ready to move on.