Skip to content

// Engineering - November 4, 2026

Code review checklist for AI agent pull requests.

A code review checklist for an AI agent's pull request has two parts. The first is what any review checks: design, behavior, tests and readability. The second is four checks for agents: the change meets the task's acceptance criteria, the evidence is real, the agent stayed in scope, and no risky files changed unnoticed.

What is a code review checklist?

A code review checklist is a short list of questions a reviewer answers for every pull request, so each review covers the same ground whoever does it. It doesn't replace judgement. It makes sure the routine checks still happen on a busy day.

A checklist needs a bar to check against. The clearest one we know is in Google's public code review guide, where a "CL" (changelist) is what other teams call a change or pull request: "In general, reviewers should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn't perfect." The guide calls that "the senior principle among all of the code review guidelines."

What should a code review checklist include?

Start with the areas in Google's What to look for in a code review. The quoted words are Google's; the rest is our short version of each section:

Area What to ask
Design "Do the interactions of various pieces of code in the CL make sense?" Does the change belong here?
Functionality Does it do what was intended? Think about edge cases and concurrency, and try UI changes yourself.
Complexity Can it be "understood quickly by code readers"? Is anything over-engineered for a need that doesn't exist yet?
Tests "Will the tests actually fail when the code is broken?"
Naming and comments Are names clear? Do comments explain why, not what?
Style and consistency Does it follow the style guide? Mark optional points "Nit:" so they don't block the change.
Documentation If it changes how people build, test or release the code, are the docs updated?
Every line, in context Do you understand every line, and does the change improve the code health of the whole system?

Google adds one more rule that matters here: if you can't judge part of a change, make sure someone qualified reviews it, "particularly for complex issues such as privacy, security, concurrency, accessibility, internationalization, etc."

Why do AI agent pull requests need extra checks?

Because you can't ask the author what it meant, and you usually didn't watch it work. By the time you review, the agent's session is over, so the pull request and its notes are all you have.

Anthropic's Claude Code best practices say what that evidence should look like. Ask the agent for "the command it ran and its output, or the screenshot. 'All tests pass' on its own tells you very little, and reading the output is faster than rerunning the check yourself. For a session you weren't watching, it's also the only evidence you have."

GitHub's docs on reviewing Copilot's pull requests add two practical points, as of November 2026:

  • Same bar as people. "Copilot pull requests deserve the same thorough review as any contribution." GitHub's risks and mitigations page adds that Copilot cloud agent "cannot approve or merge a pull request", and that the person who asked it for a pull request can't approve that pull request. Where approvals are required, someone else has to review it.
  • Watch the CI files. By default, GitHub Actions workflows don't run automatically when Copilot pushes to a pull request. Workflows "can be privileged and have access to sensitive secrets", so inspect the change before you click Approve and run workflows, and "be especially alert to any proposed changes in the .github/workflows/ directory."

Size is the other early check. Google's Small CLs page says "100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large", that the number of files counts too, and that reviewers "have discretion to reject your change outright for the sole reason of it being too large." If an agent's pull request is too large, split the card, not just the pull request, so the next attempt starts small.

What is on the checklist for an AI agent's pull request?

Do the agent checks first, then the usual review. If the change doesn't match the task or has no evidence, a line-by-line read is wasted time. Copy this into your pull request template or review notes:

## Before the diff
- [ ] The PR belongs to one card, and the card is in Needs review
- [ ] The hand-off comment marks every acceptance criterion pass or fail
- [ ] Every "pass" has evidence: the command and its output, a test name, a screenshot
- [ ] The change does one thing and is small enough to read in one sitting

## Scope
- [ ] Every changed file is one the card's task needs
- [ ] Nothing the card lists as out of scope changed
- [ ] No renames, reformatting or refactors mixed in with the fix
- [ ] No code for a future the card doesn't ask for

## Risky files (read every line)
- [ ] CI and workflow files, such as .github/workflows/
- [ ] Dependencies and lockfiles
- [ ] Database migrations, auth, permissions, billing
- [ ] Secrets: no keys, tokens or .env contents in code, logs or comments
- [ ] Agent config: CLAUDE.md, AGENTS.md, .claude/settings.json, hooks

## Tests
- [ ] New behavior has a test that fails without the change
- [ ] No existing test was deleted, skipped or loosened to make the run pass
- [ ] CI ran on this branch, not only the agent's own local run

## The usual review
- [ ] Design, functionality, complexity, naming, comments, style, docs
- [ ] You understand every line, and the change leaves the code healthier

Most items need no explanation. These do:

  • Evidence, not claims. "Pass" in a comment is a claim. A command with its output, a named test or a screenshot is evidence. If a criterion has no evidence, send it back before you read the code.
  • Loosened tests. A green run proves nothing if a test was changed to match the new behavior. Google's guide puts it plainly: "Tests do not test themselves," and "a human must ensure that tests are valid." Read every changed test as closely as the code.
  • Agent config files. A change to CLAUDE.md, AGENTS.md or .claude/settings.json changes how every later agent session behaves. Settings files can also hold hooks, which the docs describe as commands and other handlers "that execute automatically at specific points in Claude Code's lifecycle." Treat these like CI files. Anthropic's own review service reads its REVIEW.md instructions "from the base or default branch and never from the pull request's own changes", so a pull request can't rewrite the reviewer's instructions.
  • Scope. Google asks authors not to mix major style changes with other changes, because it "makes it hard to see what is being changed." The same goes for an agent's extra refactor: ask for it as its own card.

Review is faster when the agent's hand-off already answers the checklist. Add this to the agent's instruction file, next to the board rules from our human-in-the-loop setup:

When you open a pull request for a Flux card:
- Change only what the card's task needs. If you notice anything else,
  mention it in your comment instead of fixing it.
- Never edit the card's title or description.
- Post one hand-off comment that starts with your agent name and lists:
  the PR link; each acceptance criterion as pass or fail with its evidence
  (the command and its output, a test name or a screenshot); the files you
  changed; any change to CI, dependencies, migrations, auth or agent config,
  and why; anything you did not finish.
- Move the card to Needs review. Never move a card to Done.

How do you review an agent's pull request from a Flux board?

Start from the card, not the pull request: the card says what was asked, and the hand-off comment says what the agent claims it did. Flux, task management for AI agent teams, is a kanban board that agents use through the Flux MCP server or the REST API and people use in a browser. New Flux boards start with To Do, In Progress and Done, so add a Needs review column between In Progress and Done first. A review from Needs review goes like this:

  1. Open the card. If the agent or a script linked the pull request, the link sits in the card's GitHub PR field. Otherwise it is in the agent's hand-off comment.
  2. Read the description first. That is the brief the agent had. Over MCP, the get_card tool returns the card's fields, including its description, and its comments, but not its checklist items, label list or assignees. If your criteria live only in the checklist, an agent working over MCP never saw them. Our acceptance criteria guide shows how to write them into the description.
  3. Read the hand-off comment. Check that every criterion has a result and evidence. Comments made with an API key show under the name of the person who created the key, so the agent's name at the start of the comment is how you tell which agent wrote it.
  4. Review the pull request in GitHub, with the checklist above.
  5. Decide. If it passes, merge it and move the card to Done yourself. If not, comment on the card with what to change and move it back to the column the agent picks up from. get_card returns every comment on the card, oldest first, so the agent's next session reads your feedback.

Three things about the card itself, checked against the Flux code on November 4, 2026:

  • The criteria can change. An agent with a Write key can rewrite a card's title and description with the MCP update_card tool, and changes made over MCP are not yet written to the Flux activity log. Keep "never edit the card's title or description" in the agent's instructions, and if the criteria look different from what you agreed, ask before you review against them.
  • The PR link. MCP update_card can't set the GitHub PR field, so agents on MCP put the link in their hand-off comment. Agents or scripts that use the REST API can set it, which puts the link in the card's GitHub PR field:
# Set the card's GitHub PR field (API key with the Write scope)
curl -sS -X PATCH https://flux.umin.ai/api/cards \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cardId":"CARD_UUID","githubPrUrl":"https://github.com/org/repo/pull/123"}'
  • Done isn't locked. Flux doesn't stop a Write key from moving a card to Done, so "never move a card to Done" is an instruction, not a lock. Check the Done column for cards nobody reviewed. To move cards automatically when a pull request merges, see the GitHub Actions setup.

Can an AI review an AI agent's pull request?

Yes, as a first pass that a person reads. The tools that sell AI review say so themselves. Anthropic's Code Review docs (a managed service for Team and Enterprise plans, as of November 2026) say "A review never approves or blocks the pull request, so the decision to merge stays with your team," and "A review with no findings doesn't mean your code is error-free or secure."

On any plan, Claude Code's /code-review command reviews the changes on your branch, and in a terminal session it runs as a background subagent. The best practices explain why a fresh reviewer helps: it "reviews the diff in a fresh subagent that never saw your conversation. It isn't swayed by the reasoning that produced the code." For agent work, point that reviewer at the card instead of a general bug hunt. This is Anthropic's review-against-spec prompt, adapted to a Flux card (use the card's ID, which get_board lists):

use a subagent to review this branch against Flux card CARD_UUID:
read the card with get_card, check every acceptance criterion is
implemented and has a test, list any changed file the card's task
doesn't need, report gaps that affect correctness and skip style

Keep the last line. Anthropic's note on its own prompt: "A reviewer that's asked to find problems will always find something. If you fix every finding, you end up with extra abstraction layers and tests for cases that can't happen."

When should you approve, fix or send back an agent's pull request?

Approve when the change meets the card and clearly improves the code, even if it isn't how you would have written it. That is Google's standard. The rest, in our practice:

What you find What to do
Meets every criterion, only style nits left Approve. Leave the nits marked "Nit:" or skip them.
A criterion fails, or a pass has no evidence Send it back. Name the criterion and the evidence you need.
Out-of-scope changes mixed in Send it back without them, and make a new card if they're worth doing.
Too large to read well Split the card into smaller cards, then close or cut down the pull request.
A one-line fix you can make faster than you can explain Push the commit yourself (GitHub lists this as a way to request changes on Copilot's pull requests) and say so on the card.
The wrong solution to the right problem The card was unclear. Close the pull request, rewrite the criteria, and move the card back to the column the agent picks up from.

If you track reviews on a board of their own, our code review board template has columns from Submitted to Merged. For agent work, the agent's own card usually does the job: it holds the task, the hand-off and the pull request link.

// FAQ
06 questions
01

What should be on a code review checklist?

+

The areas in Google's public code review guide: design, functionality, complexity, tests, naming, comments, style, consistency, documentation, and every line read in context. For an AI agent's pull request, add four checks: it meets the acceptance criteria, each pass has evidence, it stayed in scope, and no risky files such as CI workflows, dependencies or secrets changed unnoticed.

02

How big should a pull request be for code review?

+

A pull request should be one self-contained change. Google's guide says "100 lines is usually a reasonable size" and "1000 lines is usually too large", but leaves the call to the reviewer. It counts files too: a 200-line change spread across 50 files is usually too large. A reviewer can reject a change for being too large alone.

03

Can AI code review replace a human reviewer?

+

No. Use AI review as a first pass that a person reads. Anthropic's Claude Code docs say its Code Review service never approves or blocks a pull request, so the decision to merge stays with your team. They also say a review with no findings doesn't mean the code is error-free or secure.

04

Should I run an AI agent's code before approving it?

+

Run it when reading isn't enough. Google's guide says checking behavior matters most for user-facing changes such as UI. For everything else, ask the agent for evidence. Anthropic's best practices say "All tests pass" on its own tells you very little, and that reading the command output is faster than rerunning the check yourself.

05

Does Flux review pull requests?

+

No. Flux does not read code or pull requests. It is the board where agents and people track the work: a card holds the task, its acceptance criteria, the agent's hand-off comment and a GitHub PR link, and a person reviews the pull request in GitHub and moves the card to Done.

06

How do I send an agent's pull request back on a Flux board?

+

Comment on the card with what to change, then move it back to the column the agent picks up from. When the agent next reads the card with the get_card tool, it gets every comment on the card, oldest first, so your feedback is part of its next task. Comment on the pull request as well if your agent works from PR comments.

// Review the work, not the claims

Give every agent pull request a card. Review it against what was asked.

Connect Claude Code, Codex or any MCP client to a Flux board. Agents hand off in a comment with their evidence, and a person decides what moves to Done. Free to start, and agents that connect with a member's API key never take a seat.