AI Coding Review Template

Use this template before merging AI-generated code. It makes the reviewer compare the diff against the spec instead of judging whether the output merely looks reasonable.

ai-coding-review.md

# AI Coding Review

Spec:
Agent or tool:
Reviewer:
Date:

## Scope Check
- Allowed files:
- Files changed:
- Out-of-scope changes:

## Spec Alignment
- Acceptance criteria satisfied:
- Criteria missing:
- Behavior added outside the spec:

## Evidence
- Tests added or updated:
- Test command:
- Manual check:
- Logs or screenshots:

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

When to use this template

A code change was generated by an AI assistant or coding agent.
The diff touches files beyond the requested area.
A reviewer needs to separate useful implementation from unspeced behavior.
The team wants a repeatable approval gate for generated code.

What a filled version looks like

The template becomes useful after it carries a real decision, owner, and evidence. This is the level of specificity to aim for.

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

## Spec Alignment
- AC-2 replay idempotency: satisfied
- Added behavior outside spec: none

Review before implementation

Changed files match the allowed-file list or the exception is explained.
Every behavior addition maps back to the spec.
Tests cover the acceptance criteria, not just implementation details.
Out-of-scope refactors are removed or split.

Weak vs strong wording

Weak

The AI code looks good and tests pass.

Strong

The diff only touches allowed files, AC-2 maps to retry.test.ts, no new provider behavior was added outside the spec, and npm run test -- refunds passes locally.

FAQ

Should reviewers trust AI test summaries?

No. The template asks for the command and evidence so reviewers can reproduce or inspect the result.

What should happen to extra behavior?

Remove it, split it into a new spec, or explicitly update the current spec before merge.

Can this be used without AI?

Yes. It is also a useful checklist for any large or risky PR, but it is written for AI drift control.

Related resources

Editorial note

This template is written for spec-driven development workflows. The example is illustrative and should be adapted to your domain.

Author: Daniel Marsh
Editorial policy: How we review and update content

Tip: keep it under /docs/specs/ or /.specs/, then update it in the same pull request as implementation changes. Last updated: May 11, 2026.