Delegating to agents without losing the thread

Rebuilding this site and moving it off AWS was one continuous piece of work: survey an unfamiliar codebase, design the change, execute it across a hundred files, verify it, ship it. The interesting question was not whether an agent could do the pieces. It was how to split the pieces up without ending up responsible for a result nobody actually understood.

A few things that worked, and one that did not.

Fan out on reading, never on deciding

Reading a codebase parallelises beautifully. Two agents went out at the start: one mapping routes, components and styling, the other mapping tests, CI and deploy. They came back with a picture that would have taken an hour to build by hand.

They also came back with things I would not have gone looking for. The project's CLAUDE.md claimed Next.js 15 and a blue colour palette; the repo was on 16 with a completely different design token system. A linked docs/TESTING.md had been deleted months earlier and was still referenced twice. The default Open Graph image referenced in the layout did not exist, which meant every page on the site had been advertising a 404 to every scraper that visited.

None of that is deduction. It is coverage — the kind of unglamorous breadth-first reading that parallel agents are genuinely good at, and that a single attention has to ration.

Deciding is the opposite. When two planning agents came back with designs, the useful output was not the plans. It was the two places they disagreed, which is exactly where the real decision was.

Treat agent output as a claim, not a result

The planning agents were right about most things and confidently wrong about several. One asserted a colour value from the approved design would pass contrast checks; it computes to 3.20:1 on the page's background, which fails an error-level accessibility gate. Another was certain the feed routes would need a postbuild step to unmangle their filenames.

Both were plausible. One was wrong, and the other was wrong in the other direction — the postbuild step was never needed, and building it would have been pure waste.

The method that survived contact: every claim that determines a design decision gets a cheap verification before anything is built on it. Compute the contrast ratio. Run one build and ls the output directory. Neither takes more than a few minutes, and both times the answer changed what got built.

This is not scepticism about agents specifically. It is the same reason you do not merge a confident PR description without reading the diff.

The work has to be verifiable by someone other than the author

The thing that made the whole migration tractable was not any agent. It was that the repo could tell me when it was broken: typecheck, a real test suite, Playwright, Lighthouse gating accessibility and SEO at error level, CodeQL, and a check asserting the built artifacts exist as actual files.

Every one of those caught something during this work. CodeQL flagged a path where a filesystem-derived slug reached an href. Playwright caught seven specs still asserting markup that no longer existed — and it mattered that those gates were genuinely enforced rather than advisory, because a suite nobody runs is a suite that tells you nothing.

Delegation scales exactly as far as verification does. If you cannot check the work cheaply, spreading it across more agents does not get you more done. It gets you more unverified output, faster.

Where it did not work

The bit I would do differently: I spent time early waiting on planning agents to return before starting work that did not depend on them. Fan-out has a real cost in latency, and "wait for the comprehensive answer" is often worse than "start on the part that is already obvious."

The second: parallel agents produce parallel narratives, and reconciling four confident summaries into one true picture is work. It is worth it for breadth. It is not worth it for a question with one right answer, where a single agent and a shell command will beat a committee every time.

The shape of it

Fan out to read. Converge to decide. Verify anything a decision rests on. Keep the gates honest so the machine can tell you when you are wrong, because at some point you will be, and the only question that matters is how long it takes to find out.