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.mdor.claude/settings.jsonchanges 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 itsREVIEW.mdinstructions "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:
- 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.
- Read the description first. That is the brief the agent had. Over MCP, the
get_cardtool 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. - 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.
- Review the pull request in GitHub, with the checklist above.
- 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_cardreturns 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_cardtool, 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_cardcan'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.