CDX-301c · Module 2

Code Review Agents

4 min read

A code review agent is a CI-integrated Codex instance that reviews every PR with a consistent, documented review methodology. Unlike ad-hoc "review this PR" prompts, a review agent uses a structured prompt template that checks specific categories: correctness (does the code do what it claims?), security (any injection points, credential exposure, or auth bypass?), performance (any N+1 queries, missing indexes, or unbounded loops?), and style (naming conventions, import order, file structure).

The review agent's AGENTS.md should specify the review methodology, the output format, and the severity levels. Codex produces better reviews when given a rubric than when told to "review the code." The rubric should match your team's actual review standards — not an idealized version. If your team does not enforce import order, do not include it in the rubric. If your team is strict about error handling, give it a dedicated section with examples of good and bad patterns.

Multi-pass review improves quality. The first pass checks for correctness and security (high-value, model-intensive). The second pass checks for style and documentation (lower-value, cheaper model). Running both passes costs more but catches issues that a single pass misses. Route the first pass to o3 with high reasoning and the second pass to gpt-4.1-mini for cost efficiency.

# Code Review Agent

## Review Methodology
Review each file in the diff against these categories:

### Critical (must fix before merge)
- Security vulnerabilities (injection, auth bypass, credential exposure)
- Data loss risks (destructive operations without confirmation)
- Breaking changes to public APIs without version bump

### Important (should fix before merge)
- Missing error handling (unhandled promises, empty catch blocks)
- Performance issues (N+1 queries, missing pagination, unbounded loops)
- Missing tests for new business logic

### Suggestion (nice to have)
- Naming improvements for clarity
- Documentation gaps
- Code simplification opportunities

## Output Format
JSON array of review comments, each with:
- file: relative file path
- line: line number
- severity: "critical" | "important" | "suggestion"
- message: the review comment (be specific, include fix suggestion)

Do This

  • Define a structured review rubric with severity levels and specific checks
  • Use multi-pass review: o3 for correctness/security, cheaper model for style
  • Output structured JSON that can be programmatically posted as PR comments
  • Track review agent accuracy — measure false positives and missed issues over time

Avoid This

  • Tell Codex to "review the code" without a rubric — reviews will be inconsistent
  • Use the most expensive model for style checks — it is overkill and wastes budget
  • Post review agent findings as blocking reviews — use advisory comments instead
  • Skip review for small PRs — small changes can have outsized impact