Codex agent teams and the review bottleneck

The promise and the arithmetic

Codex agent teams mean several agents working concurrently on separate slices of a task. The pitch writes itself: four agents, four times the work. The arithmetic does not hold, and the reason is not the model.

A senior engineer reviews maybe 400 lines of unfamiliar diff per hour before quality drops off. Four agents can produce that in minutes. So the queue forms at the human, and every extra agent past the review capacity adds latency instead of removing it. We have seen a team of six run eight parallel agents for a week and ship less than the week before, because everyone was reading diffs instead of thinking.

Partition by blast radius, not by ticket

The instinct is to split work by Jira ticket. That is wrong, because two tickets often touch the same files. Split by what the change can break.

• One agent per top-level directory or service, never two in the same one.
• Schema and data-layer changes run alone, with nothing else in flight.
• Anything touching shared types goes first, then the rest starts after it lands.
• Test-only and docs-only work can run alongside almost anything.
• Config and CI changes get their own slot, because a broken pipeline blocks every other agent's verification.

Write the partition down before you start. Give each agent the boundary in its instruction: only modify files under services/billing/. If the fix requires a change elsewhere, stop and report it. Agents obey that instruction far more reliably than they obey a vague request to be careful.

Making the output reviewable

The single change with the largest effect is requiring each agent to produce a short written rationale next to the diff. Not a commit message. A note saying what it understood the problem to be, what it changed, and what it deliberately left alone.

That note lets a reviewer decide in 30 seconds whether to read the diff carefully or skim it. Without it, every diff gets the same treatment, which means the risky one gets the same attention as the typo fix.

Second change: make every agent run the same verification command before reporting done, and make it paste the output. If your test command is npm test -- --run, put that in AGENTS.md and require the tail of the output in the report. An agent that says "tests pass" without evidence is right about two thirds of the time in our experience, which is not good enough to build on.

Where Codex agent teams break down

Merge conflicts between agents are the obvious one, and partitioning handles most of it. The subtler failure is duplicated abstraction. Two agents solving related problems independently will each invent a helper, and you end up with formatCurrency in two places with different rounding. No conflict, no test failure, and a bug six weeks later.

The other one is nobody owning the whole. Each diff is defensible and the sum is incoherent. Someone has to hold the design, and that someone cannot also be reading four diffs an hour.

What to do next

Cap the number of concurrent agents at half your available reviewers and hold it there for two weeks. Write the partition on a whiteboard before each batch. Then measure merged pull requests, not agent runs. If the number does not move, the constraint was never the coding.

If you want help putting this into practice, talk to us.