Standardising Codex agents across an engineering team

The shape of a Codex agents team rollout

By the time a Codex agents team rollout is discussed formally, three people are already using it and two of them have opinions. That is fine. The job is not to introduce the tool, it is to stop five different private workflows from becoming five different code styles in the same repo.

Three artefacts do most of the work, and none of them take longer than an afternoon to write.

The three artefacts

• A shared AGENTS.md, committed. One page. Build and test commands, directories that are generated or off limits, the logging and error conventions, what CI enforces. This is the difference between five agents writing five idioms and five agents writing yours.
• A written review policy. Not "review AI code carefully". Something checkable: diffs over 400 lines get split, anything touching auth or payments gets a named human reviewer regardless of what any automated pass said, and the author resolves machine review comments before requesting human review.
• Agreed defaults in config. Sandbox and approval level in ~/.codex/config.toml, set conservative. Document how to raise it and when raising it is appropriate, because people will, and you would rather they do it deliberately.

Disclosure, and why it is worth the friction

Decide whether agent-generated changes get marked. We lean towards yes, as a trailer in the commit message rather than a badge on the PR. It costs nothing and it gives you something real six months later: when you are tracing the origin of a class of bug, you can actually query how the code got written. Teams that skipped this and later wanted the data could not reconstruct it.

The objection is that it creates a two-tier review culture. In practice we have not seen that, provided the policy says every change is reviewed the same way. If your reviewers are treating human diffs as trustworthy by default, you had that problem already.

Measure the thing that matters

Teams reach for lines of code or number of agent sessions, and both mislead. Lines go up. That is not a result.

Track cycle time from ticket start to merged, and track change failure rate. If cycle time drops and failures hold steady, the rollout worked. If both go up, you are shipping more code and more defects, which is the specific failure mode we get called in to fix. Also worth watching: review queue depth. Agents make writing cheap and reviewing expensive, and the queue is where that shows up first.

How to run the first month

Pick one team, not the whole org. Write the three artefacts in a single session with the people who will use them. Set a review date four weeks out with the two metrics above already being collected, so the review is a conversation about numbers rather than about who liked it. Then take what that team learned and let them write the version for everyone else.

We do this as a working day with an engineering team, leaving with the files written rather than a slide deck about them.

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