Generated code review

AI Coding PR Review Checklist

Do not review AI-generated code by asking whether it looks plausible. Review it by comparing the diff against the spec, criteria, allowed files, and evidence.

Copy review template Write criteria first

Last updated: May 25, 2026

Review In This Order

Scope first

Check changed files before reading style or implementation details.

Criteria second

Map each accepted behavior to a named acceptance criterion.

Evidence third

Require tests, screenshots, logs, metrics, or manual checks for each criterion.

AI Review Needs A Different First Pass

AI-generated diffs often include useful code and quiet extras in the same patch. A normal style-first review may miss the extras because the useful part looks correct.

The first pass should be mechanical: files changed, contracts preserved, criteria satisfied, evidence present. Only then is it worth reviewing naming, structure, or implementation taste.

Reviewer Stop Signals

  • The diff touches files outside the allowed write scope.
  • A criterion has no matching evidence.
  • The agent changed public contracts without approval.
  • The PR bundles a refactor with the requested behavior.
  • The final answer does not mention known gaps or skipped checks.

Copy-Ready PR Review Checklist

Paste this into the PR description or reviewer comment before approving generated code.

ai-pr-review.md 
# AI Coding PR Review

Spec:
Agent/tool:
Reviewer:

## 1. Scope Check
- Allowed files:
- Actual files changed:
- Out-of-scope changes:

## 2. Acceptance Mapping
- AC-1:
- AC-2:
- AC-3:

## 3. Evidence
- Tests added or updated:
- Test command and result:
- Manual check, screenshot, log, or metric:

## 4. Contract Check
- API shape preserved:
- DB schema preserved or migration reviewed:
- Events, permissions, and error codes preserved:

## 5. Decision
- Approve | Request changes | Split PR
- Follow-up owner:
- Notes:

Filled Example

A strong review record makes it obvious whether the agent followed the original spec.

filled-example.md 
## Scope Check
- Allowed files: services/refunds/*, tests/refunds/*
- Actual files changed: services/refunds/retry.ts, tests/refunds/retry.test.ts
- Out-of-scope changes: none

## Acceptance Mapping
- AC-1 retry once on timeout: retry.test.ts "retries once"
- AC-2 double timeout response: retry.test.ts "keeps retryable failure"
- AC-3 invalid signature: existing signature test still passes

## Evidence
- npm test -- refunds
- Manual: PR diff shows no provider API change

## Decision
- Approve with follow-up: add production metric alert in next spec.

What To Reject

Unmapped behavior

The diff adds behavior that is not tied to a criterion, non-goal exception, or approved follow-up.

Unproven tests

The PR says tests pass but does not show the command, relevant case, or CI result.

Quiet contract changes

A response field, schema, permission, or event payload changed without being listed in the spec.

Related Resources

Pair this checklist with the spec and criteria pages so review has a source of truth.

AI Coding Review Template

Use a longer reusable review artifact for generated PRs.

Copy template

AI Coding Acceptance Criteria

Write criteria that can be mapped directly to review evidence.

Write criteria

Claude Code Spec Template

Give the coding agent a scope boundary before the PR exists.

Open spec

AI PR Review FAQ

Should reviewers trust AI final summaries?

No. Treat them as claims until commands, tests, screenshots, logs, or diff evidence support them.

What if the extra behavior is useful?

Split it into a follow-up spec or update the current spec before merge. Do not hide it in the same PR.

Should review start with code style?

No. Start with scope, criteria, evidence, and contracts. Style review comes after the change is bounded.

When a generated PR arrives, review the spec first, the evidence second, and the code third.

Copy review template