Why AI code review actually works

The case for AI code review isn't that it's smarter than an experienced senior engineer. It isn't. The case is different: it's consistently thorough in ways that humans aren't, it never gets tired or rushes because a PR is blocking a deploy, and it reviews every line with equal attention regardless of how obvious or boring the code looks.

Human reviewers are very good at catching architectural problems, spotting whether an approach fits the codebase, and identifying missing business logic. They're genuinely bad at finding the forgotten console.log left in, noticing that a variable shadows an outer scope in a subtle way, or catching that an error message will be shown to users in English on a localized site.

Claude (and GPT-4 class models) are good at exactly that second category. When you route the right kind of review task to AI, you stop asking human reviewers to do work that neither party finds valuable.

Setting up the review context

The biggest mistake in AI code review is sending the diff with no context and asking for feedback. You get generic, often irrelevant observations because the model doesn't know what the code is trying to do.

A good Claude code review prompt always starts with context:

  • What is this code doing? One sentence.
  • What should I focus on? Security? Logic errors? Edge cases? Style?
  • What's the environment? Production? Shopify? React? Node.js?
  • What have I already considered? Save time by ruling out known issues upfront.

Prompt patterns that work

The general review prompt

You are reviewing a pull request for a Shopify theme. The change adds a cart drawer with Ajax-based add-to-cart. Review the JavaScript file below.

Focus on: error handling gaps, duplicate submission prevention, accessibility of the drawer (focus management, aria attributes), and any edge cases that would cause incorrect cart state.

Do NOT flag code style unless it's a real readability problem. Do NOT suggest refactors unless they fix a bug or close a real risk. Be specific about what line or pattern has the issue.

[paste code here]

The key constraints at the end ("do not flag code style", "be specific about line") are critical. Without them, Claude fills the response with style suggestions that waste your time and bury the real issues.

The security-focused review

Review this code for security issues only. Language: JavaScript (browser). Context: this code processes user input from a form and sends it to a Shopify Ajax endpoint.

Look specifically for: XSS vectors (unsanitized HTML injection), CSRF risks, insecure direct object references, improper input validation before sending to API, any data exposed that shouldn't be.

For each issue: state the line, the risk category, severity (high/medium/low), and a one-line fix.

[paste code]

The logic audit

This function is supposed to: calculate the correct discounted price for a product bundle where items over $50 each get 10% off and the total gets an additional 5% off if there are 3 or more items.

Look for logic errors, off-by-one errors, rounding issues, and cases where the function returns a wrong result. Show me an input/output pair where it would fail, if any.

[paste function]

The "explain before you criticize" prompt

When you're reviewing code you didn't write and are unsure whether an approach is intentional:

First, explain in 2–3 sentences what this code does and what design decisions seem intentional. Then flag any bugs, risks, or issues you see. Skip anything that looks like a deliberate stylistic choice.

[paste code]

This two-step approach prevents Claude from flagging intentional patterns as problems. The explanation step forces it to understand the code before criticizing it.

What Claude catches well vs poorly

Catches reliably

  • Missing null/undefined checks that would throw in edge cases
  • Race conditions in async code (missing await, overlapping requests)
  • Forgotten error handling branches
  • DOM XSS via innerHTML with unsanitized data
  • Hardcoded strings that should be variables or config
  • Accessibility gaps: missing aria attributes, focus not managed
  • Inconsistent error messages or states
  • Obvious naming confusion (variable names that lie)

Catches poorly

  • Business logic errors (if it doesn't know the requirements)
  • Performance problems that require profiling data
  • Whether the approach fits the broader codebase architecture
  • Subtle race conditions in distributed systems
  • Knowing when "good enough" is actually fine for the context
  • Missing tests for specific business scenarios

Integrating into a PR workflow

The most practical integration point is before you request a human review. Run Claude on the diff yourself, fix the easy issues it finds, and submit a cleaner PR. This makes the human review faster and more focused on the things that matter.

# Get the diff for your branch vs main
git diff main...HEAD -- '*.js' '*.liquid' '*.ts' | pbcopy

# Paste into Claude with your review prompt
# Fix issues found
# Then open the PR

For teams, you can automate this with GitHub Actions + the Claude API. The model reviews the diff on every PR and posts a comment with findings. Keep the output structured (JSON or a numbered list) so it's easy to scan:

# .github/workflows/ai-review.yml (simplified)
name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get diff
        run: git diff ${{ github.event.pull_request.base.sha }}...${{ github.sha }} > diff.txt
      - name: Claude review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          python3 scripts/claude_review.py diff.txt > review.md
      - name: Post comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('fs').readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

Don't post AI review comments directly with merge-blocking status. Claude confidently flags things that are intentional or context-dependent. Use it as informational — a first pass that the author reviews before a human reviewer looks at the PR. The human reviewer still makes the final call.

The review conversation pattern

One underused technique: treating Claude as a collaborator rather than a one-shot reviewer. After the initial review, follow up with targeted questions:

You flagged issue #3 — the race condition when two add-to-cart requests fire simultaneously. I've added a isLoading flag that disables the button during the request. Does this address the issue, or is there still a window where both requests can proceed?

[paste updated code]

This code runs in Shopify's theme context where merchants may have consent management platforms (like OneTrust) that delay script execution. Does any part of this code make timing assumptions that could break in that context?

These follow-up prompts are often more valuable than the initial review because they test specific hypotheses about your code rather than generating a broad list of potential issues.

What Claude will do that you should push back on

Claude has a strong tendency to be helpful in ways that don't help. Watch for:

  • Suggesting rewrites when you asked for a bug review. The rewrite might be fine code but it's not what you needed.
  • Flagging "could be improved" instead of "this is broken." Train your prompts to ask only for the latter.
  • Generating a list of 12 issues when 2 are real problems and the rest are preferences. Ask it to sort by severity and skip anything below a threshold.
  • Hallucinating API behavior. If it references a function or parameter that doesn't exist, it's confabulating. Verify everything against real docs.

The meta-skill is prompt design. A generic "review this code" prompt produces generic output. A constrained, context-rich prompt produces output you can actually act on. Treat your review prompts as reusable assets — save the ones that produce good output, iterate on them, and share them with your team.

Building a library of review prompts

The highest-leverage thing you can do with AI code review is invest 30 minutes building a prompt library specific to your stack. Different code contexts need different review lenses:

  • Shopify Liquid sections: Focus on schema correctness, translation key coverage, missing default values, accessibility of rendered HTML
  • JavaScript event handlers: Focus on memory leaks (listeners not removed), incorrect this binding, missed error states
  • API integration code: Focus on error handling, timeout handling, rate limit responses, credential exposure
  • CSS/SCSS: Focus on specificity problems, missing responsive breakpoints, hardcoded values that should be variables

Store these in a .github/prompts/ folder in your repo, or in a shared team Notion. The prompt library is a form of institutional knowledge about what kinds of mistakes your team makes and what Claude needs to look for.