How to Review AI-Generated Code Before You Hit Merge

Claude Code can write a working change in minutes, but someone still has to decide whether it should merge. This Claude Code review checklist covers what to check in an agent-written diff before you approve it: scope, verification, dependencies, permissions and configuration, security, and whether you can explain every change. It's the same set of judgment calls our Claude Code certification assesses.

The Claude Code review checklist

1. Scope: every changed file belongs to the task you asked for.
2. No drive-by changes: no unrelated refactors, renames or formatting churn.
3. Evidence: you've seen the test or build output, not just a claim that it passed.
4. Tests weren't weakened: no deleted, skipped or loosened tests to get a pass.
5. Root cause: the fix addresses the cause, not just the symptom or the error message.
6. Dependencies: any new package, version change or lockfile change was intended.
7. Permissions and config: no unexpected changes to Claude Code settings, hooks, MCP config, CI or secrets.
8. Security: untrusted input is handled, and no keys or credentials appear in the diff.
9. The real diff: you reviewed git diff, including changes made by shell commands, not only Claude's summary.
10. You can explain it: you could defend every change to a reviewer without asking Claude.

1. Check the scope first

Start with the file list before you read any code. If you asked for a fix to the login timeout and the diff touches billing, that's your first finding. Agents often tidy up nearby code, rename things for consistency or reformat files they opened. Each of those may be harmless on its own, but together they make the change harder to review and harder to revert.

Anthropic's own Claude Code best practices include this check in their suggested review prompt: confirm that "nothing outside the task's scope changed." The cheapest way to keep scope tight is upstream. For multi-file changes, use plan mode so Claude explores and proposes a plan before it edits anything, then compare the diff against that plan.

2. Ask for evidence, not reassurance

Claude stops when the work looks done. The best-practices guide recommends giving it a check it can run, such as tests, a build or a linter, and having it "show evidence rather than asserting success": the command it ran and what that command returned. When you review, look for that output. If it isn't there, run the checks yourself.

Then read the tests, not just the result. A suite can go green because a failing test was deleted, skipped or rewritten to expect the wrong value. Also check that the change fixes the cause. Anthropic's guide gives the example prompt "address the root cause, don't suppress the error", which is exactly the habit a reviewer should check for.

3. Treat new dependencies as a decision

Look at package.json, requirements.txt, lockfiles and any vendored code. A new library might be fine, but it should be a choice someone made, not a side effect. Ask whether the codebase already has a library that does the job, whether the package is maintained and licensed in a way you can accept, and whether a version bump elsewhere in the lockfile was intended. If you want Claude to avoid adding packages, say so in the task, as Anthropic's guide does with "build from scratch without libraries other than the ones already used in the codebase."

4. Check permissions and configuration changes

Some files change what the agent, or your pipeline, is allowed to do next time. Give these extra scrutiny:

• .claude/settings.json and other settings files, which hold permission rules and hooks
• CLAUDE.md, which Claude reads at the start of every session
• .mcp.json, which defines project MCP servers
• CI workflows, deployment config and anything that handles secrets

Anthropic's Claude Code security guidance is explicit that you're responsible for reviewing proposed code and commands before approval, and recommends that you "verify proposed changes to critical files." It also notes that reviewing .mcp.json doesn't show every MCP server a session can load, because servers can be configured outside the repository too. Before the agent runs unattended, decide what it may touch using permission rules and sandboxing, rather than relying on review afterwards.

5. Look for the usual security problems

AI-written code needs the same security review as any other code, and it doesn't always get it. Veracode's testing found that 45 percent of AI-generated code samples failed basic security tests; we break that research down in our post on AI code vulnerabilities. In the diff, trace user input to where it's used, look for string-built queries and commands, and search for anything that looks like a key or token. Claude Code also has a built-in /security-review command for an on-demand pass over your branch's changes, which is a useful second check rather than a replacement for yours.

6. Review the real diff, not the summary

Claude's end-of-task summary describes what it believes it changed. Review the actual git diff. This matters because changes made through shell commands can sit outside what you watched. Anthropic notes that Claude Code's checkpoints "only track changes made through Claude's file editing tools", so files changed by a script, a code generator or a migration command won't be undone by rewinding. Your version control is the source of truth.

7. Make sure you can explain every change

The final check is the simplest and the most telling. Could you walk a colleague through each change, and say why it's safe, without asking Claude? If not, you aren't ready to approve it. This is the habit we weight most heavily in our assessment, where engineers explain their review of an agent's diff to a human assessor before it merges.

Tools that make review easier

• A fresh-context reviewer. Anthropic recommends having a subagent review the diff in a fresh context, or running the bundled /code-review skill, because a reviewer that didn't write the code isn't biased toward it. Its guide also warns that a reviewer asked to find gaps will usually report some, so ask it to flag only issues that affect correctness or the stated requirements.
• Hooks for non-negotiables. Hooks run scripts at set points in Claude's workflow. Unlike CLAUDE.md instructions, which are advisory, Anthropic describes hooks as deterministic, so use them for checks that must happen every time, such as linting after edits or blocking writes to a protected folder.
• Plan mode for bigger changes. Reviewing a plan before any code exists is faster than reviewing a large diff afterwards.

Copy this checklist into your PR template

## Agent-written change review
- [ ] Every changed file is in scope for this task
- [ ] No unrelated refactors, renames or formatting churn
- [ ] I saw test/build/lint output (not just "tests pass")
- [ ] No tests were deleted, skipped or loosened
- [ ] The fix addresses the root cause
- [ ] New or changed dependencies were intended
- [ ] No unexpected changes to .claude/, CLAUDE.md, .mcp.json, CI or secrets
- [ ] Untrusted input is handled; no keys or tokens in the diff
- [ ] I reviewed git diff, including shell-made changes
- [ ] I can explain every change without asking the agent

Want it on paper or in your repo? Download the printable checklist (PDF) or the ready-made PR template (.md), free from our resources page.

A checklist helps, but it only works if people apply it under time pressure. If you need to know which of your engineers do, that's what our Claude Code certification checks: engineers are assessed on reviewing agent diffs in a proctored task in a live repository. For the wider argument, read the vibe coding tax and should companies certify their Claude Code teams.

Sources: Best practices for Claude Code; Claude Code security; Configure permissions; Veracode 2025 GenAI Code Security Report. Anthropic documentation checked 6 October 2026.

Rolling this out across a team? See the Claude Code rollout playbook and how to measure Claude Code impact.