Skip to content

C.L.E.A.R. code review

Context · Logic · Edge-cases · Architecture · Readability

C.L.E.A.R. is code review, reframed for the era of AI-generated diffs. The reviewer's job is no longer just "does this code work?". It is "does the human who is asking me to merge this understand what they are asking?"

Reviewing AI-generated code as if it were human-written misses the defects most likely to be present. Reviewing it as adversarial human-written code (mistrusting every line) is exhausting and burns out reviewers. C.L.E.A.R. is the middle path.

Why review changes for AI

DORA's 2024 Accelerate State of DevOps report found that AI tool adoption correlated with throughput drops of 1.5% and stability drops of 7.2% per 25% of adoption: gains in individual flow offset by losses in team-level outcomes1. The intervention point that closes the gap is review: who reviews, how, and against what standard.

When to use C.L.E.A.R.

Every PR. The depth, and the reviewer composition, scales with the risk classification of the system.

Tier Reviewers Time budget
Low One reviewer, same team 5–15 min
Medium One reviewer, may be from same team 15–30 min
High Two reviewers, one from outside immediate team; AppSec for security paths 30–60 min
Critical Two reviewers including a named Architect; AppSec sign-off on security paths; Decision Record required 60+ min

The author has already run V.E.R.I.F.Y. and, where applicable, S.E.C.U.R.E.. The reviewer's job is what those checks cannot catch from the inside.

The five parts

C. Context

Before reading the diff:

  • Read the PR description. A diff with no description is a draft, not a request for review. Send it back.
  • Read the linked issue, ticket, or Decision Record. What is this supposed to do? Whose problem does it solve?
  • Read the prompt. If the PR was AI-assisted, the prompt should be in the PR description (per the AUP). Without the prompt, the reviewer cannot detect intent drift.
  • Read the surrounding code. A diff that fits the file in front of you may not fit the system as a whole.

A reviewer who skips Context is grading the spelling of an essay without reading the question.

L. Logic

Now read the diff. For each non-trivial line:

  • Does this do what the description says?
  • Does this do only what the description says? AI-generated PRs routinely include "while I was here" changes that drift from intent. They are scope creep with extra steps.
  • Are the **invariants preserved?** What contract does the changed function hold? Does it still hold after the change?
  • Are there silent omissions? A handler that no longer logs an error path; a function that lost a guard clause; a test that was weakened.

Models produce code that reads logically while violating an unstated invariant. The reviewer is the second set of eyes for the unstated.

E. Edge-cases

This is where AI-generated PRs most consistently fail review. The author ran the happy-path test. The model wrote a happy-path test. The reviewer asks the harder questions:

  • What happens with empty input? None? []? ""? 0?
  • What happens with adversarial input? Unicode, control characters, very long strings, deeply nested structures?
  • What happens at boundaries? Off-by-one, integer overflow, time zone crossings, daylight savings, leap seconds.
  • What happens under concurrency? Two requests racing; a retry arriving after the original succeeded; a partial failure.
  • What happens during partial failures? The first DB write succeeds, the second fails. What is the state of the system?
  • What is the failure mode? When this code fails, does it fail loud, fail silent, or fail confused?

If the diff doesn't have edge-case tests for the relevant cases, that is the finding. Don't paper over it; ask for them.

A. Architecture

Step back from the lines:

  • Does this fit the system? A new abstraction may be locally elegant and globally redundant.
  • Does this duplicate something already in the codebase? Models cheerfully re-invent helpers that already exist three directories over.
  • Does this cross a layer it shouldn't? A route handler that reaches into the persistence layer; a domain object that knows about HTTP status codes.
  • Does this introduce coupling that will be expensive to remove? Singletons, globals, hidden state, hard-coded URLs.
  • Does this respect the bounded contexts and module boundaries the codebase has?

Surface review passes for AI-generated code that fails architectural fit. This step is what the reviewer adds beyond the model's local view.

R. Readability

Last, and easy to under-weight:

  • Will the next reader (in six months, with no context) understand this? The author has the prompt and the conversation in their head. The next reader has only the file.
  • Are the names sensible? AI-generated names skew generic (process, handler, data). Rename for the codebase.
  • Are comments earning their place? Comments that paraphrase code are noise; comments that explain why are signal.
  • Is the diff a readable size? A 2,000-line PR cannot be reviewed carefully. The reviewer's job here is to push back: split it.

Questions a reviewer should ask the author of an AI-generated PR

A useful standing checklist for the reviewer to keep alongside the diff when the PR was AI-assisted:

Reviewer's standing questions

  • Can you explain this line in your own words? Not the diff; the line. If the author cannot, they cannot own it.
  • What did you ask the assistant? The prompt, not the summary. Show me the S.C.A.F.F. block.
  • What did you change after the model produced its first draft? The revisions are where the author's judgment lives.
  • What edge case did you check that isn't in the test file? Force the author to articulate one.
  • What did you decide not to do? Models suggest scope additions; the author's judgment is in what they refused.
  • What would have to change to undo this? Reversibility is a proxy for blast radius.

These are not interrogation questions; they are the same questions a thoughtful author would ask themselves. C.L.E.A.R. just makes them explicit when AI assistance is in the loop.

Common review failures

Failure Pattern What good looks like
Rubber-stamp on green CI "Tests pass, LGTM" Read the diff; CI does not test what is missing
AI-deference "The AI wrote it, the AI is usually right" The author owns it; the AI does not have a name on the PR
Local-only view Reviewer reads the file, not the system Read at least one file up the call graph
Edge-case bypass Happy-path tests + happy-path code = green light Ask explicitly: empty, null, adversarial, concurrent
Architecture drift Each PR is locally fine, the system rots Periodic architecture review beyond per-PR review

Sizing guidance

Sizing guide

  • Small (< 50). One reviewer per PR; tier-Critical changes pair-review live. Reviewer's standing questions live in a single REVIEW.md in the repo root.
  • Mid (50–500). Promote AppSec to a required reviewer on Tier High security paths. Track review-time as a metric (see metrics taxonomy). PR template includes the prompt and the V.E.R.I.F.Y. depth.
  • Enterprise (500+). Cross-team reviewer rotations to prevent same-team echo chambers; named architects own architectural review at the tier boundary; review-time metric is reported up to engineering leadership monthly.
  • Regulated. Reviewer composition follows the RACI and the risk classification. Review evidence flows into the audit trail.
  • V.E.R.I.F.Y.: what the author should already have done.
  • S.E.C.U.R.E.: the security pass that Tier High/Critical reviews build on.
  • S.C.A.F.F.: what the prompt should have looked like; visible to the reviewer.
  • Metrics taxonomy: review-time metrics, including the SPACE / DORA / DevEx canonical set.
  • Pilot retrospective: review practice is one of the dimensions retros surface.

Anti-patterns

Don't

  • Don't rubber-stamp a green CI. CI is a backstop, not a review. Tests pass on bugs all the time, especially bugs the AI wrote alongside the test.
  • Don't lean on "the AI wrote it, so I trust it." The AI does not have a name on the PR. The author does. The reviewer does. Trust attaches to people, not models.
  • Don't review without context of the wider system. A diff that looks fine in one file may break the file two directories over that depends on it.
  • Don't accept a 2,000-line PR. Push back. AI-assisted authorship makes huge PRs cheap to write and just as expensive to review as before. Reviewer time is the constraint.
  • Don't merge without confirming the author can explain the diff. A diff the author cannot explain is one the team cannot maintain.

Next

  1. Google Cloud / DORA, "2024 Accelerate State of DevOps Report", Oct 2024. [primary] ↩