Scope first
Check changed files before reading style or implementation details.
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.
Check changed files before reading style or implementation details.
Map each accepted behavior to a named acceptance criterion.
Require tests, screenshots, logs, metrics, or manual checks for each criterion.
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.
Paste this into the PR description or reviewer comment before approving generated code.
# 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:
A strong review record makes it obvious whether the agent followed the original spec.
## 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.
A coding agent adds account search to an admin page. The diff looks helpful, but it also touches a shared query helper, changes default sorting, and removes a tenant filter in one branch.
Review the changed-file list before reading implementation details. The shared helper and tenant filter are scope questions, not style comments.
Require each accepted behavior to point to a criterion: empty query, tenant-scoped results, latency budget, and permission denial.
Approve the search behavior only after the tenant filter evidence is restored. Move sorting cleanup into a follow-up spec instead of merging it silently.
The safest AI PR review is intentionally boring at first. Reviewers should verify that the diff stayed inside scope, preserved contracts, and produced evidence before they spend energy on naming, formatting, architecture taste, or whether the generated code looks clever.
Open the file list before the code body. Compare it with the spec's allowed write scope and mark every unexpected file as a question. This prevents a reviewer from becoming attached to a useful-looking implementation that already crossed a boundary.
AI final summaries often sound certain. Require concrete proof: command output, named test cases, screenshots for UI states, migration logs, metrics, or manual QA notes. If the evidence is missing, the correct review decision is request changes, not a longer discussion.
Sometimes the extra behavior is genuinely useful. Still split it out unless the current spec is updated and reviewed. Quietly merging extra behavior trains agents to treat review as permission to expand scope, which makes future PRs harder to judge.
The diff adds behavior that is not tied to a criterion, non-goal exception, or approved follow-up.
The PR says tests pass but does not show the command, relevant case, or CI result.
A response field, schema, permission, or event payload changed without being listed in the spec.
Pair this checklist with the spec and criteria pages so review has a source of truth.
Use a longer reusable review artifact for generated PRs.
Copy templateWrite criteria that can be mapped directly to review evidence.
Write criteriaGive the coding agent a scope boundary before the PR exists.
Open specNo. Treat them as claims until commands, tests, screenshots, logs, or diff evidence support them.
Split it into a follow-up spec or update the current spec before merge. Do not hide it in the same PR.
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