Claude Code Review: What It Catches, and What It Can't

You ran your first Claude Code review and got a list back. One finding was sharp enough to stop the merge. Three were noise. Now you have no idea which half to trust next time, or what the reviewer never looked for at all.

Here is the honest shape of it: what the review reliably catches, what it half-catches, what it structurally cannot judge no matter how you prompt it, and the configuration that decides which of those you get.

Key takeaways

• Three things get called "Claude Code review": the local /code-review command, the managed GitHub App, and a review skill you write yourself. They read different config files.
• It is strongest on what it can verify by reading code: unhandled error paths, stale callers after a signature change, unscoped queries, secrets reaching logs, migration blast radius.
• It is weakest wherever judgement is required: whether the feature should exist, or whether the abstraction will hurt in six months.
• REVIEW.md is the single most useful file you can add: it recalibrates severity, caps nit volume, lists what to skip. Anthropic's docs say the managed reviewer reads it, the local command does not, and the default calibration targets correctness, not formatting or test coverage.
• Most review noise is a context problem, not a model problem.

---

Three different things people mean by "Claude Code review"

Before arguing about quality, get specific about which one you ran.

Locally. /code-review reviews your branch's commits ahead of upstream plus uncommitted changes. Pass a target for anything else: a file path, a PR number, a branch, or a range like main...my-feature. It runs as a background subagent with its own context window, so it does not eat your session.

/code-review medium                 # branch vs upstream, plus uncommitted work
/code-review high main...my-feature # broader coverage on a specific range
/code-review --fix                  # apply the findings to your working tree

Effort level is the dial most people miss. The docs are explicit: low and medium report only the findings the review is most confident in, while high through max broaden coverage and may include findings it is less sure about. If you are drowning in nits, lower the effort before blaming the model. One gotcha: a background --fix lands outside your session checkpoints, so /rewind will not undo it. Use git.

On pull requests, managed. An organisation Owner enables Code Review in the Claude Code admin settings, installs the Claude GitHub App, picks the repositories in scope, and sets a Review Behavior per repo: once after PR creation, after every push, or manual. Manual is the sane default for a busy repo, because you opt PRs in by comment:

@claude review          # one review, no subscription
@claude review always   # review now, and on every later push
@claude review once     # same as the bare command

The docs are strict about form: top-level PR comment, command at the start, from an account with owner, member, or collaborator access, on an open PR. Under the hood, Anthropic describes multiple agents analysing the diff in parallel, then a verification step that checks candidates against actual code behaviour. Survivors post as inline comments tagged Important, Nit, or Pre-existing, plus a Claude Code Review check run that always completes neutral, so it never blocks a merge. Two boundaries: it is a research preview on Team and Enterprise plans, unavailable with Zero Data Retention enabled, and the docs put it at $15 to $25 per review. That is why "review on every push" is a decision, not a default.

In your own CI. To run Claude in your own infrastructure instead, the docs point to GitHub Actions or GitLab CI/CD. You then own the trigger logic, the prompt, and the filtering.

What the reviewer actually catches

An AI reviewer is excellent at work that is tedious, mechanical, and verifiable by careful reading, which is exactly what human reviewers skip when they are tired.

Error paths nobody tested. The happy path gets reviewed because the PR description describes it. The reviewer reads the branches you did not: the failed parse, the timed-out call, the empty list. Anthropic's own worked example is a function that silently returns 0 on malformed input, so the caller cannot tell "zero" from "broken".

Breaking changes with stale callers. You changed a signature, updated three call sites, missed the fourth in a directory you never open. An agent with repository access finds it by searching, not by remembering.

Mechanical consistency. Every other module validates at the boundary and this one validates halfway down. Every other handler returns a typed error and this one returns a string. No human catches these across a 40-file diff.

Known security patterns. Query concatenation, a database call not scoped to the caller's tenant, a request body reaching a log line, a non-constant-time token comparison. Shape matching is what the model is good at.

Blast radius. You bumped a dependency or added a migration. The interesting question is everything downstream of the diff. An agent with the whole codebase in reach traces the callers and the tables. A reviewer in a browser tab does not.

The thread connecting all five: it is good at everything boring and checkable.

What a review agent structurally cannot judge

This is the section the docs do not write, because it is a boundary rather than a bug list.

Whether the feature should exist. The reviewer reads the diff and assumes the diff is wanted. It will help you build the wrong thing correctly, and be encouraging about it. The most valuable comment in code review has always been "why are we doing this at all", and no review agent leaves it, because the question lives outside the code.

Whether it matches a convention nobody wrote down. Your team stopped using the ORM's lazy loading eighteen months ago after an incident. That decision lives in a chat channel, in two people's heads, and in a PR thread nobody can find. The reviewer sees clean, idiomatic, correct lazy loading and approves it. Not a prompt problem: the information is genuinely absent.

Whether the abstraction will hurt in six months. Judging an abstraction requires knowing what is coming: the two roadmap features this shape will not accommodate, the integration you are about to sign. The reviewer sees a reasonable interface. The senior engineer sees the interface plus next quarter.

The product and org cost of a change. That one enterprise customer depends on this endpoint. That the platform team is mid-migration on the service you just touched. None of this is fixable with a bigger model, only by writing the missing context where the reviewer can read it.

Review categories, scored honestly

The "reliably" band is work you can stop doing by hand. The "not at all" band is what human review is now for.

A review pass worth running

A default review gives you default findings. Anthropic's docs describe REVIEW.md as review-only instructions handed to the agents that find and verify findings, and consulted by the ones that rank them. Drop this at your repository root and edit it.

# Review instructions

## What Important means here
Reserve Important for anything that breaks behaviour, leaks data, or blocks a
rollback: incorrect logic, queries not scoped to the caller's tenant, PII in
logs or error messages, migrations that are not backward compatible.
Naming, style, and refactor suggestions are Nit at most.

## Cap the nits
Report at most five Nits per review. If there are more, say "plus N similar
items" in the summary. If everything found is a Nit, open with
"No blocking issues."

## Do not report
- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rules

## Always check
- New API routes have an integration test
- No log line includes an email address, a user ID, or a request body
- Every database query is scoped to the caller's tenant
- A change to a public function updates its callers and its docs

## Verification bar
Behaviour claims need a `file:line` citation, not an inference from a name.

## On re-review
After the first review, suppress new nits and post Important findings only.

Keep it short: the docs warn that a long REVIEW.md dilutes the rules that matter most.

Then the pass itself. Before accepting a review as done, walk this list:

1. Did it check the error branches, not just the path the PR describes?
2. Did it search for callers of anything whose signature changed?
3. Did it say whether the tests assert behaviour or only shape?
4. Did it flag docs and comments the change made untrue?
5. Did it catch anything contradicting CLAUDE.md or REVIEW.md?
6. What did it not look at, and is that the risky part of this change?

Question six is the one that pays. If you would rather start from a review pass someone has already tuned than a blank file, our code review skills hub collects the ones we published for this job, installable as a Claude Code plugin marketplace with /plugin marketplace add mkhalid1/locul-skills. Judging whether a review skill is worth keeping is its own problem, because more findings is not the same as better findings. Five of the 114 skills there carry measured before-and-after results, six more were tested and cut, and nineteen were retired, so the testing methodology is worth reading before you trust any skill directory, ours included. Writing your own? How Claude Code skills work covers the frontmatter that makes one fire reliably.

The part nobody configures: the reviewer does not know your conventions

Every improvement above is the same move: give the reviewer more of what your team already knows. REVIEW.md writes down severity, CLAUDE.md writes down conventions, a skill writes down a process. All three work, and all three hit the same wall.

The standards that actually govern your codebase are not written anywhere. They are in the head of the engineer who has been there four years, in a PR comment from March that settled an argument and then scrolled out of reach, in the postmortem that produced a rule nobody turned into a lint check. A new engineer learns them by being corrected over months. A review agent never does: nothing corrects it, and nothing persists.

A reviewer that does not know your conventions is not reviewing your code. It is reviewing generic code.

That is why the second review of a repository is rarely better than the first. You fix a finding, explain why it was wrong, and next week it files the same finding again. Writing rules into CLAUDE.md by hand helps and is the right first move, but that file only holds what someone remembered to type, and it goes stale the moment a decision changes. That maintenance loop is what keeping an AI setup current is really about, and it sits underneath Claude Code memory and CLAUDE.md best practices too.

That is the problem Locul exists for: a local-first desktop app for macOS and Windows that builds a second brain from what you already produce, keeps it current as your decisions change, and serves it to Claude Code over MCP. When a rule changes, the old memory is marked superseded instead of sitting there contradicting the new one.

FAQ

How do I review code with Claude Code?

Run /code-review in the session where you are working. With no arguments it reviews your branch's commits ahead of upstream plus any uncommitted changes. Pass a target for anything else: a file path, a PR number, a branch name, or a range like main...my-feature. Add an effort level to trade confidence for coverage, --fix to apply findings, or --comment to post them on the PR.

Is the Claude Code review any good in practice?

It is genuinely good at one band of work and useless at another. It reliably catches unhandled error paths, stale callers after a signature change, inconsistencies across a large diff, common security patterns, and docs the change made wrong. It cannot judge whether the feature should exist, whether the change breaks an unwritten convention, or whether the abstraction will age badly. Treat it as a thorough first pass, not an approval. Most noise complaints trace back to running it at high effort with no REVIEW.md.

How do I set up automated review on pull requests?

An org Owner enables Code Review in the Claude Code admin settings, installs the Claude GitHub App, selects repositories, and sets a per-repo trigger: once after PR creation, after every push, or manual. In manual mode you start a review by commenting @claude review at the top level of the PR, or @claude review always to also subscribe it to later pushes. To run it in your own infrastructure, use GitHub Actions or GitLab CI/CD. Cost scales with PR size and trigger frequency.

What does Claude Code miss in review?

Anything requiring information outside the repository: unwritten conventions, the roadmap that decides whether an abstraction is right, the customer who depends on the endpoint you changed, the incident that produced a rule nobody wrote down. It also only partially handles concurrency bugs, performance regressions that depend on real traffic, and test quality, where it sees a weak assertion but not which behaviour matters. Anthropic's docs say the managed review targets correctness by default rather than formatting or test coverage, so silence there is scope, not approval.

Where to go next

Start with the boundary, not the tooling. Decide which band of the table you are delegating, write the REVIEW.md that says so, then pick a trigger you can afford. That takes an afternoon and it is most of the value.

For the wider picture of working with an agent on real code, read what an AI coding assistant is good and bad at. And if your reviewer keeps re-litigating rules you already settled, the fix is upstream of the review config: the Locul demo shows what it looks like when your decisions stay current on their own.