AI Code Review

Every change must be reviewed by AI before it is pushed. This is not optional, and it is not a substitute for human review. It is the quality gate that runs first, so that reviewers spend their time on judgement rather than on bugs a machine can find.

Why Codex Finds and Claude Fixes

We use two AI tools and give them different jobs, because they are good at different things.

• Codex finds the bugs. In our experience it is noticeably better than Claude at spotting real defects in a diff: off-by-one errors, unhandled edge cases, broken error paths, subtle logic inversions.
• Claude fixes them and owns the final code. Claude is the tool that has been working in the repository with you. It has the project context, the conventions, and the history of the change, so it produces fixes that fit the codebase rather than generic patches.

Running Codex as the reviewer and Claude as the author gives us an adversarial pair: the tool looking for problems is not the tool that wrote the code.

The Process

Once your change is complete and committed locally, and before you push, ask Claude to run the review loop. The instruction to give Claude is:

run `codex review --base main` until there are no bugs left, or they are not relevant.
Review findings produced if relevant.

This puts Claude into a loop:

1. Claude runs codex review --base main against your branch.
2. Codex reports its findings.
3. Claude reviews each finding, fixes the ones that are real, and explains the ones it dismisses.
4. Claude runs the review again on the updated diff.
5. The loop ends when Codex reports nothing new, or when the only remaining findings are not relevant to the change.

Only then do you push and open your Merge Request.

Judging Findings

Not every finding is a bug. Claude is expected to push back on findings that are wrong, and you are expected to read that reasoning rather than accept it silently. A finding is not relevant when:

• It describes behaviour that is intentional and documented.
• It is out of scope for the change. Pre-existing issues in code you did not touch belong in a GitLab Issue, not in this MR.
• It is a style preference already settled by our linters or our design system.
• It is factually wrong about how the code or the framework behaves.

If you are unsure whether a finding is relevant, treat it as relevant and fix it. If a dismissed finding turns out to be a real class of problem, open an Issue so we fix it properly.

Do not loop forever on cosmetic findings. The goal is a diff with no real bugs left, not a diff that Codex has run out of opinions about.

Where This Fits

This runs before the steps described in Merge Requests :

1. Self-review your own diff.
2. Run the AI review loop described on this page.
3. Ask the AI for a final check: clean code, no duplication, tests added or updated, security considered, documentation updated.
4. Push, open the MR, and assign reviewers.

Human reviewers should not be finding bugs that codex review would have caught. If they are, the loop was not run.

Setup

Both tools are installed as part of Engineer Onboarding . If codex review is not available, revisit the OpenAI Codex CLI section of that page.