Code Review With Claude Code: Catch Bugs Before They Reach Production

What Is Claude Code Review?

Claude Code Review is a multi-agent code review system that examines a PR in the context of the repo and reports potential bugs, security issues, and regressions. GitHub Code Review runs those agents against a GitHub PR, while local /code-review gives you a review of your current diff directly from Claude Code.

The important word here is context. A conventional diff review asks someone to inspect the lines that changed. Claude's review agents examine those changes within the context of the repo. The GitHub workflow has multiple specialized agents working in parallel, followed by verification, deduplication, and severity ranking.

For instance, a 10-line change to a pandas transformation can depend on the schema created by an upstream dbt model, the grain of a Snowflake table, and assumptions embedded in a downstream dashboard.

Claude neither approves nor blocks a PR. GitHub Code Review reports a neutral check conclusion, so your existing branch protection rules remain unchanged unless you build your own CI logic around the check output.

Three review surfaces

There are currently 3 main ways to review code with Claude Code.

The local /code-review command examines your branch's commits. You can also give it a specific file, branch, PR number, or Git ref range.

GitHub Code Review is designed around the PR itself. Depending on the repo configuration, it can review once after PR creation, after every push, or only when someone requests a review with @claude review.

/code-review ultra is the heavier option. Anthropic calls the feature ultrareview, and /ultrareview works as an alias when the feature is available to your account. It runs a fleet of reviewer agents in a remote sandbox, with each reported bug reproduced and verified before it appears in the findings. This is currently a research preview, and a typical review takes about 5 to 10 minutes.

What Claude flags vs. what it skips

Claude Code Review focuses on correctness first. Anthropic's documentation specifically distinguishes production-impacting bugs from formatting preferences and missing test coverage.

The findings use 3 severity levels:

That distinction is useful because data scientists often have very different opinions about what deserves review time. A naming suggestion about revenue_df versus weekly_revenue is not in the same category as multiplying revenue by 2 because a many-to-many join slipped into a transformation.

How Do You Set Up Code Review in Claude Code?

Setting up Claude Code Review requires different steps depending on whether you want a local review or a GitHub PR code review. Local /code-review does not require the GitHub App and can be done before you even open a PR. 

The GitHub Code Review requires an organization Owner or Primary Owner to configure the Claude GitHub App and select repos. When doing PR reviews, you’ll want to create a specialized file called REVIEW.md that holds specific review-only rules.

CLAUDE.md vs. REVIEW.md

CLAUDE.md and REVIEW.md serve different purposes, and mixing them together is an easy way to create noisy reviews.

CLAUDE.md contains general project instructions that Claude uses across tasks. Code review reads those instructions too, and newly introduced violations are reported as nits.  REVIEW.md, on the other hand, is specifically for review behavior and tells the review agents what your team wants flagged, skipped, or treated as Important.

For a Python data repo, I would keep CLAUDE.md focused on things such as the repo structure, how to run pytest, whether transformations use pandas or polars, and where SQL models live. 

I would put review rules in REVIEW.md. A few examples of potential rules:

• “Check every new transformation for a corresponding test.”
• “Never log credentials."
• “Skip generated files."

A small  REVIEW.md might look like this:

# Review instructions

## Important findings

Report as Important:
- Incorrect joins or filters that can change dataset grain
- Missing tenant or customer scoping
- Secrets or credentials written to logs
- Silent changes to revenue or customer metrics

## Do not report
- Formatting already enforced by Ruff
- Generated files
- *.lock files

## Always check
- New transformations have tests
- Joins use the intended keys
- Datetime operations specify timezone assumptions
- Missing values are handled explicitly

I recommend keeping your REVIEW.md focused because long instructions can dilute important rules. The current implementation also reads the file as plain instructions, so you should put rules directly into it instead of using the @ shortcut. 

By the way, when you’re developing locally, /code-review does not read  REVIEW.md. It follows CLAUDE.md, while the GitHub Code Review pipeline uses  REVIEW.md for review-specific instructions.

If you want the same review rules locally and in GitHub, put the general rules in CLAUDE.md and repeat the review-specific rules in REVIEW.md where necessary.

For a deeper dive, I recommend reading our guide on writing the best CLAUDE.md file.

GitHub App and trigger mode

GitHub Code Review is configured by an organization's Owner or Primary Owner through Claude's admin settings. The admin needs to install the Claude GitHub App, grant it repo access, select the repos to review, and then assign a review behavior to each repo.

There are 3 different trigger modes:

One exception to all 3: Claude never automatically reviews a pull request from a fork. Someone has to comment @claude review on it.

As of the July 2026 update, the manual commands have also changed: 

• @claude review starts a single review and does not subscribe the PR to future pushes. 

• @claude review always starts a review and subscribes the PR to future push-triggered reviews.

• @claude review once behaves the same as the bare command.

If you learned Claude Code Review earlier in 2026, older tutorials may have said that @claude review subscribes the PR to future reviews, but that behavior changed in July 2026 and remains true as of September 2026.

Pro and Max users who do not have access to the organization's GitHub Code Review can skip the App entirely and use /code-review locally, with /code-review ultra for a deeper review.

How Do You Review a Diff Locally With /code-review?

The local /code-review command reviews your current branch before you open a PR. I always start with this because it catches problems while I am still working and can prevent failing CI.

The case to review

Let's imagine we have an e-commerce repo with an orders table containing order_id, customer_id, order_date, status, and revenue, and we create weekly_revenue.py to calculate the weekly revenue:

orders = load_orders()
customers = load_customers()

# Derive the reporting week from the order date
orders["week"] = orders["order_date"].dt.to_period("W").dt.start_time

weekly_revenue = (
    orders
    .merge(customers, on="customer_id", how="inner")
    .groupby("week", as_index=False)["revenue"]
    .sum()
)

At first glance, nothing looks strange. The merge() is explicit, the grouping is readable, and revenue is aggregated after the join.

The problem is that the customers' table contains multiple historical records for some customers. A customer with 2 records now produces 2 rows after the join, doubling the revenue attached to that customer. This is exactly the sort of bug that is easy to miss when you read the transformation locally without checking the table grain.

Scope the diff

From your Claude Code session, run /code-review.

The command reviews the current branch's commits ahead of its upstream branch, together with uncommitted changes. You can also target a particular file, branch, PR, or range, such as main...feature/weekly-revenue.

For example:

/code-review weekly_revenue.py

or:

/code-review main...feature/weekly-revenue

You can also pass an effort level, such as /code-review high. At low and medium, the review reports only the findings it is most confident about, while high through max expands coverage at the cost of more possible false positives. 

Use flags to steer the review

Once you get comfortable with the workflow, two flags start coming in handy: 

• --fix applies the findings to your working tree after the review.

• --comment posts them as inline comments.

Claude runs the review as a background subagent, so you can keep working while it processes the change. The findings return to your session when the review finishes.

The review might report something along these lines:

🔴 Important
weekly_revenue.py:9

The merge on customer_id can duplicate order rows because
customers contains multiple records per customer. This can
inflate revenue when a customer has more than one matching
customer record.

Verify that customer_id is unique in customers or join against
the intended current-record subset before aggregating revenue.

The review found a concrete failure mode and gives me something I can verify against the actual schema, rather than asking me to trust Claude's judgment.

Read the findings

I would still give everything a manual pass before running /code-review --fix. First, search for the code that builds customers, inspect its uniqueness constraints, and look at the tests around weekly_revenue.py.

If customers.customer_id is genuinely unique, Claude's finding is a false positive. If the table contains one row per customer per effective date, the finding is real, and the transformation needs to change.

The key point here is that Claude's reviewer is looking at code behavior, while I am still responsible for knowing what the data represents.

You can ask Claude to investigate after the review:

Investigate the customer_id join finding.
Check how the customers table is built and determine whether
customer_id is unique at the point of this merge. Do not modify
the code yet.

That second step is often more useful than asking Claude to blindly fix the comment. It turns review into a brief investigation rather than a code-generation exercise.

How Do You Run Claude Code Review on a GitHub PR?

GitHub Code Review puts Claude's findings directly on the PR, so reviewers can see the issue beside the changed code. 

The order matters because the review attaches to a PR that already exists:

1. Push the weekly-revenue branch to GitHub via git push.

2. Open the pull request. Claude can only review an open PR, so nothing happens before this point.

3. If the repo is set to an automatic trigger, the review starts automatically. If it is set to Manual, post @claude review as a top-level PR comment to start one.

Three requirements trip people up here. The command must be a top-level PR comment rather than a reply to an inline review comment, and you need write, maintain, or admin permissions on the repo. The command also has to start the comment, with once or always on the same line if they are added.

Trigger the review

The choice that actually costs you money is between the two manual commands, not between manual and automatic.

@claude review runs one review and leaves the PR unsubscribed. @claude review always runs a review and subscribes to the PR, so every later push starts a fresh one.

This is the behavior after July 2026 and as of September 2026. Before that update, the bare @claude review command subscribed the PR to future reviews, so if you are following an older tutorial, check this first.

The review often takes about 20 minutes, although Anthropic says cost and duration depend on PR size and complexity. Each review is also billed separately through usage credits rather than consuming the included usage of the Team or Enterprise plan. If you want to know more about the cost structure, I recommend reading our guide to Claude Code usage limits.

Read the inline comments and the check run

When the review finishes, Claude posts inline comments on the relevant lines. The GitHub check run also includes a severity summary, which is useful when a PR has multiple findings across weekly_revenue.py, SQL models, and test files.

For example:

The inline comment is where I would investigate the actual issue. The check run is where I would get the overall shape of the review.

Just a note, clicking 👍 or 👎 does not trigger another review, and replying to an inline comment does not make Claude respond. To get another review, fix the code and push, or post @claude review as a new top-level PR comment.

The review also does not block merging on its own. The check provides a neutral conclusion, although the check output includes machine-readable severity information that a team can consume via gh and jq if it wants to build its own merge gate.

How Do You Triage Claude's Review Comments?

The whole point is to keep the human in the loop during the review cycle. This means every Claude review requires deciding whether each finding is a real bug, a non-blocking improvement, or a false positive. This is because a code reviewer can inspect implementation behavior without knowing every business assumption behind a dataset or metric.

I use a simple 3-way decision:

That last category is important. A reviewer who reports 30 findings is not necessarily better than one who reports 5. A false-positive comment about a pandas merge can cost more time than the original code change.

Fix, skip, or push back

If the duplicated customer rows bug is real, I might ask Claude to inspect the upstream model and then make the following fix:

The customer_id finding is valid. Inspect the existing customer
model and update weekly_revenue.py to join only the current
customer record. Add a regression test for a customer with
multiple historical records, then run the relevant tests.

Claude can then inspect the repo, change the Python code, add the test, and run the test suite.

If you want to work from GitHub review comments, Claude Code can also interact with the repo through the GitHub CLI (gh). The important distinction is that I would pick and choose the specific fixes you think are valid, rather than give it the entire review to "fix everything."

This keeps developers in the review loop:

1. Claude finds a possible problem.
2. I verify the problem against the code and data assumptions.
3. Claude makes the requested fix.
4. Tests run.
5. Claude reviews the resulting diff again.

That loop is much safer than treating the first review output as an automated refactoring queue.

What does a data PR still need a human for?

The failure mode Claude can't cover is code that runs correctly and still does the wrong thing. Three versions of that show up over and over:

• Assumptions that live outside the diff. Claude reads your repo, not your data warehouse, your config service, or the contract another team owns. A join can use the right keys and still change the grain of the result, because the number of rows per key is a property of the upstream table, not of the code in front of you.

• Definitions only your team holds. Whether revenue should be counted at the order, customer, or week level is a business decision. Claude can tell you a groupby() will happily sum whatever rows it is given. It cannot tell you which number your finance team signs off on.

• Time and type assumptions. Does 2026-08-27 mean a UTC day, a local business day, or a reporting date set by an upstream model? Silent coercion has the same shape: operations across object, nullable integer, timezone-aware datetime, and string columns can return something plausible while quietly changing how comparisons behave.

Data leakage is the sharpest example of the first category. A feature transformation can join a training set to a table containing information that only existed after the prediction date. The join is valid, the row count is what you expected, and the model is corrupted.

So I treat Claude as a reviewer of implementation behavior, not the owner of the definition.

When Should You Use Code Review vs Ultrareview?

Use /code-review for fast local feedback and /code-review ultra for a deeper pre-merge pass. Both review code, but /code-review is designed for iteration, while the ultra review runs multiple remote agents and independently verifies reported bugs.

Anthropic currently describes ultra review as a research preview. Pro and Max subscribers receive 3 free runs as a one-time allotment that does not refresh, after which a review typically costs $5 to $25, depending on the size of the change. Team and Enterprise users do not receive those free runs, and the feature is unavailable on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and for organizations with Zero Data Retention enabled.

The important difference is verification. /code-review ultra sends the repo state to a remote sandbox and runs a fleet of reviewer agents, with reported bugs independently reproduced before they are returned as findings.

I would not run it on every commit. If I am changing a variable name in a Python notebook or adjusting a dbt model's formatting, a local /code-review is plenty. If I am changing the feature-generation logic for a production model, rewriting a revenue transformation, or modifying a customer-level aggregation, the extra review pass makes more sense.

There is also a naming detail worth getting right. The documented command is /code-review ultra, and /ultrareview is an alias that works when ultrareview is available to your account. Older tutorials often present /ultrareview as the primary command, but Anthropic's documentation now treats the deep cloud review as part of the /code-review command family, and /code-review ultra falls back to a local review when the cloud feature is unavailable.

Run the ultra review on the same PR

From the repo, run:

/code-review ultra

To review a GitHub PR directly:

/code-review ultra <pr#>

Without an argument, /code-review ultra compares your current branch with the default branch and includes uncommitted and staged changes. A branch review caps at around 500 changed files and 8,000 changed lines by default, though Anthropic notes that these numbers can change. If your diff is too big, push the branch and review it as a PR instead.

With a PR number, the remote environment clones the PR from GitHub, and nothing is uploaded from your machine.

Before starting, Claude shows the review scope, remaining free runs, and estimated cost. After confirmation, the review runs in the background, so you can keep using Claude Code while the remote agents work.

For our weekly_revenue.py example, I would compare the findings rather than assume the deeper review must be right.

If /code-review flags the customer join and the ultra review independently reproduces the same revenue duplication, my confidence in that finding increases. If the ultra review ignores it because the upstream table guarantees uniqueness, I would inspect the evidence from both reviews and the actual model definition before changing the code.

That is a useful property of multiple reviewers: disagreement gives you something to investigate.

There is also a cost consideration. GitHub Code Review currently averages $15 to $25 per review, while the ultra review typically costs $5 to $25 after its free Pro and Max runs. GitHub Code Review costs are separate from included plan usage, and Anthropic provides spend controls for organizations.

If you are working alone, local /code-review plus an occasional /code-review ultra is a reasonable starting workflow. If you are on a Team or Enterprise plan and want every PR to carry an automated review, GitHub Code Review makes more sense.

A Practical Claude Code Review Workflow

The useful workflow is not "run Claude before every merge." It is a sequence where each review happens at a different point in development, because each one costs a different amount and catches a different class of problem.

Here is the process I would use for a production change:

Write code
	   ↓
Run tests and data checks
	   ↓
/code-review
	   ↓
Fix verified findings
	   ↓
Open GitHub PR
	   ↓
GitHub Code Review
	   ↓
Human triage
	   ↓
/code-review ultra for higher-risk changes
	   ↓
Final tests
	   ↓
Human merge

The local review catches problems while they are cheap to fix. The GitHub review provides the broader team with a shared record of findings, while the ultra review offers a higher-effort second opinion before a consequential merge.

Additional checks for data scientists

For data work, I would add 4 checks around Claude rather than expecting the model to perform the entire review:

• Check row counts and dataset grain before and after important joins
• Run unit or integration tests around transformations and feature logic.
• Check for leakage when building machine learning features.
• Validate business metrics against a known-good query or dashboard.

Claude can participate in all 4 activities, but the expected result should come from code, tests, or data rather than Claude's explanation.

Final Thoughts

Claude Code Review works best when I treat it like another engineer on the review thread, not like an automated approval stamp.

The local /code-review command gives you a quick review before the PR exists. GitHub Code Review brings multi-agent findings into the PR for Team and Enterprise organizations, while /code-review ultra gives you a deeper remote review when the change deserves another pass.

I would start small. Put /code-review into your normal branch workflow, write a short REVIEW.md for your GitHub reviews, and try /code-review ultra on changes where a bad merge would actually cost you something.

For the underlying model concepts, our Introduction to Claude Models course provides the broader context, while GitHub Foundations and Intermediate GitHub Concepts cover the Git and GitHub workflow that Code Review sits on top of. For more inspiration on how to triage GitHub repos with Claude, I also recommend reading our Claude Code connector tutorial.