Skip to main content

The Code Review Cycle

In one line: Two stages — spec compliance first (right thing built?), then code quality (built right?). Every finding gets one of three dispositions: fixed, acknowledged, or disputed.

Code review is a two-stage process. The stages serve different purposes and catch different categories of defects.

Stage 1: Spec Compliance Review. The reviewer (human or agent) reads the design specification and the implementation, and checks whether the implementation delivers what the specification promised. This catches:

  • Missing features that were specified but not implemented
  • Divergences where the implementation chose a different approach than the specification without documenting why
  • Scope creep where the implementation added behavior not in the specification

If divergences are found, there are two valid resolutions: fix the implementation to match the spec, or update the spec with a rationale for the change. "Silently diverging" — implementing something different from the spec without updating the spec — is never acceptable because it makes the spec unreliable as a reference.

Stage 2: Code Quality Review. The reviewer checks the implementation for engineering quality independent of the specification:

  • Are established patterns followed? (Repository pattern for database access, service layer for business logic, router layer for HTTP concerns)
  • Are tests sufficient? (Coverage thresholds met, edge cases covered, error paths tested)
  • Is error handling appropriate? (Not silently swallowing exceptions that should propagate, not leaking internal details in error responses)
  • Are security concerns addressed? (SQL injection, authentication bypass, tenant isolation, PII exposure)
  • Is the code maintainable? (Reasonable function sizes, clear naming, no unnecessary complexity)

Receiving a Code Review:

The default AI behavior under criticism is to agree immediately and implement everything — performative compliance, not engagement. The receiving-review norms counter that:

  1. Evaluate each finding on technical merit. Not all findings are correct — some rest on outdated context, a misread design, or a pattern that doesn't apply here. Judge each independently.

  2. Agree with evidence, not deference. "You're right, I'll fix that" is insufficient; state what is wrong and how the fix addresses it (or the technical reason it doesn't apply).

  3. Push back when appropriate. If a suggestion would violate the spec, add needless complexity, or degrade performance without commensurate benefit, push back with reasoning rather than comply to avoid disagreement.

  4. Track all findings. Every review finding gets one of three dispositions: fixed (with the fix described), acknowledged (accepted as valid but deferred with a tracking issue), or disputed (with technical reasoning). No finding is silently ignored.