Claude Code in a Large Codebase: Review Workflows That Actually Help

AI code review sounds great until it leaves forty comments on a pull request and thirty-eight of them are about naming. I've spent a while figuring out how to make Claude Code useful on a large codebase without that noise. Here's the workflow that stuck.

Give it the context a new teammate would need

The biggest quality jump came from writing down the things a senior engineer would tell a new hire. Claude Code reads a CLAUDE.md file in the repository, so that's where this goes.

# CLAUDE.md

## Review priorities
1. Correctness: logic errors, unhandled errors, race conditions.
2. Security: input validation, secrets, permission checks.
3. Breaking changes to public APIs or database schemas.

## Ignore in reviews
- Formatting and import order (handled by the linter).
- Naming preferences unless a name is actively misleading.

## Project facts
- All money values are integers in cents.
- Database access goes through the repository layer, never raw SQL in handlers.

This file does two jobs. It tells the model what to care about, and, just as important, what to skip. The "ignore" list cut most of the noise for me.

Review the diff, not the repo

On a large codebase, asking for a review of "the project" produces vague, generic feedback. Point it at the change instead. A simple pattern is to pipe the diff into a non-interactive run:

git diff main...HEAD | claude -p "Review this diff using the priorities in CLAUDE.md. \
List only issues that could cause a bug, a security problem, or a breaking change. \
For each, give the file, the line, and a one-sentence reason."

The explicit output format matters. Without it, you get essays. With it, you get a list a human reviewer can check in two minutes. Check the current Claude Code documentation for the exact flags in your version before wiring this into scripts.

Keep a human as the reviewer of record

I treat the AI review as a first pass, not an approval. A person still owns the merge decision. In practice, the AI catches the tedious things (a missing null check, an error swallowed in a catch block), and the human spends their attention on design and intent.

Two rules that helped the team trust the output:

1. Every AI comment has to point at a specific line. Comments without a location get ignored.
2. If an AI comment turns out to be wrong, someone adds a line to CLAUDE.md so it doesn't happen again.

That second rule turns false positives into documentation. After a few weeks, the file becomes a useful description of how the codebase actually works. I wrote up a longer look at real costs and production results from Claude Code reviews, including where it falls short.

Run security checks as a separate pass

I don't mix security review into the general review prompt. A single prompt that tries to check correctness, style, and security tends to do all three halfway. Instead, I run a second, narrow pass that only looks for things like secrets in code, missing permission checks, and unvalidated input reaching a database query.

The output goes into the same PR, labelled separately. Reviewers know that anything in the security list deserves a closer look, even when the general review looks clean.

Watch cost and scope

Large diffs cost more and get worse reviews. I ask for smaller pull requests anyway, and the AI review is one more reason. If a diff is huge, split the review by directory.

I also don't run it on every push. It runs when a PR is opened or marked ready, which keeps costs predictable.

Measure whether it's helping

The question isn't "is the AI smart?" It's "are we catching more real issues before merge, with less reviewer time?" Track how many AI comments lead to a code change, and how many get dismissed. If dismissals stay high, tighten the priorities in CLAUDE.md.

What's in your review context file, and which instruction cut the most noise for you?

I'm Darius Tran, and I work on getting AI into real engineering and operations workflows at AI Hive.