Designing a Codex agent team for one feature

The feature

Say the task is adding CSV export to an admin dashboard. Backend endpoint, a queue job because the export is slow, a download link in the UI, and an audit log entry because someone in compliance asked. It is a normal two-day ticket.

The wrong instinct is to hand the whole ticket to one agent and hope. The other wrong instinct is to spawn four agents on the four bullets above and let them meet in the middle. Both produce something that compiles and neither produces something you want to merge.

Decide the contracts yourself

Before any agent starts, you write down three things by hand. It takes fifteen minutes and it is the whole difference between a Codex agent team that works and one that generates rework.

• The endpoint signature. Path, method, request shape, response shape, error codes.
• The job payload. Exactly which fields the queue message carries.
• The audit event name and its fields.

Those are the interfaces between the slices. Agents are poor at negotiating interfaces with each other and good at implementing one you specified. Every integration mess we have watched in a workshop traces back to an interface nobody wrote down.

Split by file boundary and run in the right order

First, alone: the agent that adds the types and the shared contract. Nothing else runs until that lands, because everything else imports from it.

Then, in parallel: one agent on the endpoint and job under the API directory, one on the UI under the web directory, one on the audit logging. Each gets a boundary in its instruction, written as a hard constraint:

Only modify files under apps/api/. The export contract is already defined in packages/types/export.ts. Do not change that file. If your task requires changing it, stop and report why.

The stop-and-report clause is the part people leave out. Without it an agent will quietly widen a shared type to make its own slice compile, and the next agent's build breaks for reasons that look unrelated.

The handoff back to you

Require the same three-part report from every agent. What it changed, in one paragraph. What it did not do and why. The output of the verification command, pasted.

Reading four of those takes five minutes and tells you where to spend the next hour. Compare that to opening four diffs cold. The reports are also where you catch the disagreement early: if the UI agent says it assumed the response returns a signed URL and the API agent says it returns a job id, you found the bug before merging rather than in staging.

What stays with you regardless: whether the feature is the right feature, whether the export should be paginated, and whether exporting customer data needs a permission check the ticket did not mention. No agent will raise that third one. It is not in the diff.

Try it on your next ticket

Take a feature you were about to do sequentially. Spend fifteen minutes writing the interfaces first, then split it three ways with explicit directory boundaries and the stop-and-report rule. Compare the merge experience against the last feature you delegated without doing that. The difference shows up on the first attempt.

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