Checklist

The Pull Request Checklist for AI-Written Code

Most pull request checklists were written for code a person typed, ran and understood before asking for review. Code written by an assistant or an agent arrives differently: it looks finished, it is often larger than asked for, and the steps that used to catch bugs before review (running it, clicking through it, writing the test) are the ones most easily skipped.

This checklist is built around the reasons AI-written pull requests get sent back. Work through it before you open the PR, and use the last section when you are the one reviewing. A copy-ready template for your repository is at the end.

1. Before you open it: scope

Oversized and wandering diffs are the first thing reviewers push back on. Cut the PR down to the change that was asked for.

  • The PR does one thing.

    Assistants tend to tidy whatever else is in the file. Move refactors, renames and formatting into their own PRs so the reviewer reads only the change that matters.

  • The diff is small enough to read in one sitting.

    Review guidance drawn from SmartBear's study at Cisco recommends reviewing a few hundred lines at a time at most. If yours is bigger, split it into stacked PRs.

  • No unrelated files changed.

    Check lockfiles, config, generated files and snapshots. Anything you can't explain in the description shouldn't be in the diff.

  • Every new dependency is justified.

    Before accepting a new package, check whether the project already has a helper or library that does the job.

Read moreOver-Scoped AI Diffs and Reviewer Cognitive Load

2. Verify it yourself

Reading a generated diff is not the same as checking it. Do the steps a reviewer will assume you did.

  • You ran it and used the changed behaviour.

    Code can compile, pass CI and still do the opposite of what was asked. Run the flow you changed, by hand, before asking anyone else to look.

  • You tried the failure paths.

    Bad input, empty states, timeouts, missing permissions. Generated code is usually written for the happy path.

  • New tests fail without the change.

    Run them against the base branch. Watch for weakened assertions, skipped tests and snapshots updated to match whatever the code now does.

  • Every API, option and import really exists.

    Check calls against the documentation for the version your project pins. Invented functions and parameters look like working code until they run.

  • CI is green for the right reason.

    No disabled checks, no new lint or type-check suppressions, no tests marked as skipped to get the build through.

Read moreWhy AI-Generated PRs Fail Code Review

3. Make it fit the codebase

The rules that get AI code rejected are often the ones nobody wrote down. Compare the diff with the code around it, not just with the task.

  • Naming, error handling and logging match nearby code.

    Use the same error types, the same logger and the same naming patterns as the module you're in.

  • No safeguard was dropped.

    Read the removed lines as carefully as the added ones. Rewritten code can quietly lose a guard clause, a retry or a permission check.

  • Security conventions still hold.

    Input validation, authorisation checks, secret handling and what gets logged should follow the same rules as the rest of the project.

  • The written rules were followed.

    CONTRIBUTING files, style guides and agent instruction files (such as AGENTS.md) only help if the tool was pointed at them and the output was checked against them.

Read moreImplicit Coding Conventions AI Tools Consistently Violate

4. Describe it honestly

The description is what the reviewer reads first. A generated summary that promises more than the diff does costs you their trust.

  • It says what changed and why, and links the issue.

    One or two sentences on the change, one on the problem it solves.

  • The description matches the diff.

    Reread a generated description against the code. Remove claims the diff doesn't support, and mention anything the diff does that the description leaves out.

  • It says how you tested it.

    The commands you ran and what you checked by hand, so the reviewer knows what is left to check.

  • It says where AI wrote the code, if the project asks.

    Read the project's contribution guidelines. Where disclosure is expected, name the tool and which parts you reviewed line by line.

  • It points the reviewer at the risky part.

    Name the file or function you're least sure of. It is faster for everyone than hoping it gets noticed.

Read moreReviewer Feedback Patterns on AI-Written Code

5. If you're the reviewer

Review habits built for human-written code miss what AI code gets wrong, because it fails in ways that look competent.

  • Read the description against the diff first.

    If they disagree, stop there and send it back. You'd be reviewing the wrong change.

  • Run the riskiest path yourself.

    A clean, consistently formatted diff is not evidence that it works. Check out the branch for anything touching data, auth or money.

  • Look for what's missing.

    Deleted guards, branches with no test, error cases that are swallowed rather than handled.

  • Ask the author to explain a line you don't follow.

    If the person who opened the PR can't explain it, it isn't ready to merge.

  • Send back a PR that is too big to review properly.

    Skimming a large diff and approving it is how defects reach production. Ask for it to be split instead.

Read moreReviewer Fatigue From High-Volume AI PR Throughput

A pull request template to copy

Put the checklist where authors will see it. On GitHub, a file named pull_request_template.md in the repository root, in docs/ or in .github/ fills in every new pull request's description.

Save this as .github/pull_request_template.md:

## What this changes
<!-- One or two sentences. One concern per PR: split refactors and renames out. -->

## Why
<!-- The problem it solves. Link the issue: Closes #123 -->

## How I verified it
<!-- What you ran and what you checked by hand, not just "tests pass". -->
- [ ] Ran it locally and exercised the changed behaviour
- [ ] Tried the failure paths (bad input, empty state, no permission)
- [ ] New or changed tests fail without this change

## Checklist
- [ ] The diff contains only this change (no drive-by edits, no unrelated files)
- [ ] Every new dependency, API and import exists and is needed
- [ ] Naming, error handling and logging match the code around it
- [ ] No check, guard or test was removed or weakened to get CI green
- [ ] This description matches what the diff actually does

## AI assistance
<!-- If your project asks: which tool, which parts it wrote, and what you reviewed line by line. -->

## Where to look closely
<!-- The riskiest part of the diff, or anything you're unsure of. -->

GitLab, Bitbucket and other hosts support description templates too, in their own locations; check your host's documentation for where the file goes.

Keep reading