How to Use Claude for Code Review

A backend engineer at a mid-size e-commerce company merged a pull request that Claude had reviewed and approved. Forty minutes later, checkout was down for roughly 12% of traffic — a race condition in inventory decrementing that only showed up under concurrent load. The code review hadn't caught it, and the postmortem revealed why: the prompt asked Claude to "review this code for bugs and style issues," which is broad enough that it defaulted to what's easiest to catch — naming conventions, missing error handling, unused imports — rather than what actually mattered here, concurrency behavior.

The Problem the Engineer Faced

The team, a five-person backend group at the e-commerce company, had started using Claude for a first-pass code review before human review, mainly to catch obvious issues before burning a senior engineer's time. It worked well for weeks. Then a pull request touching the inventory service went through the same process and got a clean bill of health, when in fact it introduced a subtle bug: two concurrent requests could both read the same inventory count before either wrote back the decrement, allowing overselling under load.

The Wrong Approach

The prompt they'd been using looked like this:

Review this pull request for bugs, style issues, and best practices. 
Here's the diff:

[diff pasted here]

What this does: it asks for a general review without telling Claude what kind of code this is or what failure modes matter most, so the review defaults toward surface-level issues that are equally visible in any codebase — spacing, naming, obvious null checks — rather than domain-specific risks like race conditions, which require knowing the code touches shared, concurrently-accessed state.

⚠️ Common mistake: asking for "a code review" as if it's one uniform task. Reviewing a UI component for accessibility issues and reviewing a payment service for concurrency bugs require completely different focus areas — a generic prompt applies neither focus well.

The Correct Prompt

Here's what the team rebuilt it into after the incident:

Review this pull request. Context: this code touches the inventory 
service, which is called concurrently from multiple checkout requests 
at once. 

Prioritize, in this order:
1. Race conditions or non-atomic read-modify-write operations on 
   shared state (inventory counts, especially)
2. Error handling for the payment gateway calls in this file — what 
   happens on timeout or partial failure?
3. Anything that could cause overselling or double-charging
4. Only after the above: style, naming, and minor best-practice notes

For each issue found, rate it as Critical / Moderate / Minor, and 
explain the specific failure scenario, not just "this could be a 
problem."

Here's the diff:
[diff pasted here]

What this does: it tells Claude what kind of risk profile this code has (concurrent, financial, inventory-affecting) and orders the review priorities explicitly, so critical domain risks get checked before cosmetic issues, and the severity rating forces a distinction between "this will cause an outage" and "this variable name is unclear."

⚡ Pro tip: always tell Claude what kind of system the code belongs to — concurrent, single-threaded, user-facing, internal-only — since the highest-value bugs in each category look completely different, and a generic review prompt can't infer that context from a diff alone.

Results and What Changed

Running the same historical pull request (the one that caused the outage) back through the new prompt, Claude flagged the race condition as Critical, specifically naming the read-then-write pattern on the inventory count and describing the exact concurrent-request scenario that would cause overselling. It also correctly categorized two genuine style nits as Minor, instead of mixing them in at the same visual weight as the critical issue — which had been part of the original problem, since a five-item flat list makes a race condition and a missing semicolon look equally important.

Over the following two months, the team's Claude-assisted reviews caught two more concurrency issues before merge, plus one payment gateway timeout that wasn't being retried correctly. Actually, the timeout catch surprised the team lead — it wasn't something they'd explicitly trained the prompt to look for, just a natural extension of "error handling for payment gateway calls."

How to Apply This to Your Situation

1. Name the system's risk profile up front. Concurrent, financial, user-facing, internal-only — pick the ones that apply and say so explicitly.
2. Order your priorities, don't just list categories. Put the highest-stakes risk category first.
3. Require severity ratings so critical and cosmetic issues don't get visually flattened into one list.
4. Ask for the specific failure scenario, not just "this could be an issue" — a vague warning is easy to dismiss, a concrete scenario ( "two concurrent requests could both pass this check") is harder to wave off.

⚠️ Common mistake: relying on Claude-assisted review as a full replacement for human review on anything touching money, security, or concurrency. Treat it as a strong first pass that surfaces issues for a human to verify, not a final signoff.

The severity-rating requirement is worth applying even outside high-risk services, because the failure mode it fixes — a flat list where a critical bug and a naming nitpick get equal visual weight — shows up everywhere, not just in inventory or payment code. A frontend engineer at a media company added the same Critical/Moderate/Minor structure to her component review prompts and found it changed how her team actually triaged feedback: reviewers started fixing Critical items before merge and batching Minor items into a follow-up ticket, instead of treating every review comment as equally urgent.

It's also worth telling Claude what NOT to flag. Teams that skip this end up with reviews cluttered by stylistic preferences that don't match their actual codebase conventions — a linter already enforces those, and having Claude repeat them just adds noise on top of what the CI pipeline already reports. Adding a line like "don't flag formatting or style issues already caught by our linter — focus on logic and correctness" cuts a surprising amount of low-value output.

There's a broader principle underneath all of this that applies well past code review: Claude's default behavior, when given a vague instruction, is to spread attention evenly across everything that could plausibly matter. That's useful for exploratory work and actively unhelpful for a review process where some issues genuinely matter a hundred times more than others. Naming the priority order explicitly is what fixes it, and it's a cheap thing to add to a prompt once you know it's the lever that matters.

Next Steps

Go back through your last few pull request review prompts and check whether they mention the actual risk profile of the code, or just ask for "bugs and style issues" generically. For any recurring category of code in your stack — payment handling, auth, concurrent services — it's worth writing a dedicated review prompt for that category specifically, rather than reusing one generic prompt everywhere.

Once you've got prompts tuned to your specific risk categories, keep them somewhere your whole team can pull from — PromptABCD works well here so the payment-review prompt and the concurrency-review prompt don't end up scattered across five different engineers' notes files.