AI Coding Review Checklist

Review the Change, Not the Conversation

An AI conversation can contain a persuasive plan, a confident explanation, and a long account of what the tool believes it changed. None of those is the product. The diff, the resulting behavior, and the new operating burden are the proposal you must review.

Use this review before committing any meaningful AI-assisted change. Trivial autocomplete does not need a ceremony. A change that touches customer data, permissions, money, migrations, background work, dependencies, external services, or a core workflow does.

Start from the complete diff, including lockfiles, generated files, deleted tests, configuration, and commands the tool ran. If the patch is too large to understand in one sitting, split it before reviewing it. Patch size is already evidence about whether the work remains under your control.

Write the Claim First

Before running the test suite, state what the change claims to do. A passing suite can only confirm the behavior it knows to check; it cannot recover an unstated product intention.

Write down the customer behavior, why it deserves to exist now, and what is deliberately excluded. Then name the highest-consequence mistake. For an invitation flow, the claim may be “an account owner can invite one teammate to the same account.” The dangerous mistake is not an unattractive email. It is granting access to the wrong account.

This claim gives the review a center. Without it, plausible code and unrelated improvements are difficult to reject.

Inspect in Four Passes

1. Intent and scope

Read every changed file. Find the line of product intent through the patch: input, decision, state change, customer-visible result. Reject unrelated cleanup, speculative abstractions, surprise services, weakened checks, skipped tests, and features the requirement did not earn.

Compare the implementation with existing codebase patterns. A locally clever solution can still be wrong for a product if it creates a second way to authorize requests, validate data, report errors, or run background work.

2. Behavior and failure

Trace the normal path without relying on the generated explanation. Then trace invalid input, missing state, partial completion, retries, duplicate requests, timeouts, and third-party failure where they apply. Ask what the customer sees and what state remains after each failure.

Run the relevant automated checks, but inspect what the tests prove. Tests generated beside the implementation may repeat its mistaken assumption. At least one important check should be derived from the requirement or risk boundary rather than from the code’s structure. Exercise the customer behavior manually when that is the shortest way to see the whole path.

3. Trust and data

Follow authentication and authorization separately. Identify who supplies every sensitive identifier and which authoritative state constrains it. Check validation, secrets, logs, error messages, data retention, deletion, migrations, rollback, and exposure to external tools or services.

Inspect every new or changed dependency yourself. Confirm that the package and version exist in the official registry or project, that the API is real, that the license and maintenance posture fit the product, and that the capability is worth another security and upgrade surface. A scanner can find some defects; it cannot decide whether the dependency belongs.

4. Ownership and operations

Close the AI conversation and explain the change from the code. You should be able to say why it has this shape, where it can fail, how failure becomes visible, how to support it, and how to change or remove it. Verify that comments and documentation describe the system that now exists rather than the plan the tool began with.

If production behavior will be hard to distinguish from success, add the smallest useful event, log, metric, or admin view. If recovery requires remembering the chat transcript, the change is not operable.

Copyable Ownership Review

Keep this note with the pull request, change record, or commit preparation. Replace irrelevant prompts with “not applicable” and a reason; do not tick through them silently.

# AI-assisted change: [short name]

Customer behavior:
Evidence or obligation that justifies doing it now:
Non-goals:
Highest-consequence wrong behavior:

[DIFF AND FIT]
Changed files reviewed, including generated files, config, and lockfiles:
Existing architecture or convention this follows:
Unrelated code, speculative scope, or generated complexity removed:
New dependency, service, model, job, permission, or recurring cost:
Why each addition is necessary now:

[TRUST AND DATA]
Authentication and authorization decision:
Sensitive inputs, outputs, storage, logs, and third-party exposure:
Migration, deletion, rollback, retry, and duplicate behavior:
Security or privacy boundary checked:

[PROOF]
Requirement-derived test:
Important failure-path test:
Relevant lint, type, test, build, or security checks run:
Manual customer-visible check:
Observation that will reveal success or failure in operation:

[OWNERSHIP]
Explain the change without the AI transcript:
How to debug it:
How to disable, reverse, or remove it:
Generated suggestion deliberately rejected, and why:
Residual risk accepted:

Decision: SHIP | REWORK | SHRINK | DISCARD
Reason:

A Review That Changes the Invite Flow

Suppose an AI-generated teammate-invite patch accepts both an invitation token and an account ID from the browser. Its tests pass because they submit the account ID the fixture expects. The interface works in the normal case, and the code looks tidy.

The ownership review begins from the claim: an invitation grants access to exactly one account under controlled conditions. That makes the browser-supplied account ID suspicious. A requirement-derived test substitutes another account ID while keeping the valid token. It reveals that the route trusts request data at the boundary where the invitation should be authoritative.

The founder reworks the change so the token resolves the invitation and its account. The review also removes generated role infrastructure that the one-teammate requirement did not need, verifies token expiry and single use, checks that a failed email leaves a recoverable invitation state, and records one event that support can find without exposing the token. The useful result is not a fuller checklist. It is a smaller patch with a sharper proof.

Use AI as a Second Reader, Not the Approver

An AI tool can help search for missing tests, suspicious dependencies, inconsistent patterns, or unhandled failure paths. Give it the requirement and risk boundary as well as the diff, and ask it to argue against the implementation. Then verify every finding in the code and product context.

Do not let the tool that produced the change supply the only review of it. Fluency is not independence, and an AI review can miss defects or confidently object to correct code. The shipping decision remains yours.

Make One of Four Decisions

Ship when the change does the stated job, the important risk is independently tested, the trust boundary is sound, the new surface area is justified, and you can operate the result.

Rework when the job is right but a bounded flaw remains. Name the flaw and preserve the evidence that exposed it.

Shrink when the intended behavior is valuable but the patch solves a larger imagined future. Remove scope until the claim, diff, and proof fit in one review.

Discard when the product intent is unproven, the implementation cannot be made legible at reasonable cost, or accepting it would leave you responsible for code you do not understand.

The review is complete when it changes or justifies a decision. A page of checked boxes cannot take ownership of the code. You can.