Automatic PR code review with Claude Code: custom commands and project rules

Claude Code can run a systematic first pass on every pull request before a human reviewer, not to replace review, but to filter obvious issues and free attention for what matters. It’s the use case with the fastest payoff in small teams, and it’s what we configure first when integrating Claude Code into an existing workflow at Snowinch. This builds on the practical Claude Code guide; here we go deep on review.

The code review problem in small teams

In a 3–5 person team, code review is often the most underestimated bottleneck. Reviewers are also building something else, attention is split, obvious issues slip through because focus stays on business logic, and comment quality varies with whoever reviews that day.

The result is uneven review quality, not from lack of skill but from lack of time and consistent context. Claude Code doesn’t fix human review, it fixes noise: unhandled types, forgotten console.logs, functions that break project conventions, missing edge cases. Those shouldn’t reach the human reviewer.

Configuration that matters: CLAUDE.md

A CLAUDE.md file at the project root turns Claude Code from a generic assistant into a contextual one. Without it, review follows general conventions. With it, review follows your project’s rules.

For code review, the most important sections:

# Project conventions

## Architecture
- Controllers contain no business logic: delegate to service layers
- Database queries always go through the repository layer, never directly from controllers
- Nullable types must be handled explicitly, no optional chaining without a declared fallback

## Forbidden patterns
- No explicit `any` in TypeScript, use `unknown` and narrowing
- No `console.log` in production, use the internal logger (`src/lib/logger`)
- No side effects in pure functions, always separate reads from mutations

## Naming
- Test files follow `*.test.ts` in the same directory as the code under test
- Environment variables are read only from `src/config/env.ts`, never directly from `process.env`

## Critical areas
- `src/billing/`, every change needs extra attention to concurrency cases
- `src/auth/`, auth middleware changes must be checked against all roles

The example above is structural, adapt paths and rules to your codebase. Treat this file as living documentation: update it whenever the team makes a relevant architectural decision. If a convention isn’t written here, Claude Code can’t enforce it.

Custom commands for review

Claude Code supports custom commands in .claude/commands/. They’re Markdown files with instructions for a recurring task, PR review is the ideal fit.

<!-- .claude/commands/review-pr.md -->
# Review PR

Analyze changes in the staging area or the provided diff and produce a structured review.

## What to check

1. **Convention violations** defined in CLAUDE.md, report each deviation with file and line
2. **Unhandled types**, nullable variables without fallback, explicit casts without checks
3. **Missing edge cases**, empty input, empty arrays, zero values, concurrency
4. **Undeclared side effects**, functions that mutate external state without that being clear from the signature
5. **Basic security**, unsanitized user input, queries built with string concatenation

## What not to flag

- Style preferences not covered by CLAUDE.md
- Architectural suggestions that would need large refactors, open a separate issue
- Problems in untouched legacy code outside this PR’s diff

## Output format

For each issue found:
- File and line
- Problem description
- Concrete fix suggestion (not generic)

If there are no issues, say so explicitly, don’t invent comments to look useful.

Invoke it in a Claude Code session with /review-pr. You can pass a diff or let it read modified files in the working tree.

Practical workflow

The flow that works in small teams without extra overhead:

Before push: the dev runs review locally on the branch before opening the PR. Fix obvious issues, then open the PR.

# In the working directory with staged changes
claude /review-pr

Optional CI check: you can wire Claude Code in CI with the PR diff via the CLI. Not a mandatory gate, an automatic PR comment the human reviewer can read first.

CI integration depends on platform and CLI version, check official Claude Code docs for current automation options: docs.anthropic.com/claude-code.

First step of human review: the reviewer reads Claude Code’s report, validates flagged items, then reviews business logic and architecture. Mechanical noise is already filtered.

What Claude Code catches well, and what it doesn’t

Catches well: explicit convention violations, unhandled types, forbidden patterns in CLAUDE.md, obvious edge cases, explicit DRY violations.

Catches poorly: subtle concurrency issues that need reasoning about execution order, bugs that only appear with specific state combinations, architectural problems that need domain context not documented in code.

Practical rule: if the issue can be stated as an explicit rule (“no any”, “controllers don’t contain business logic”), Claude Code can find it. If it needs domain intuition or undocumented scenarios, don’t rely on it.

The risk to avoid

Treating review output as final without reading it. Teams that trust the tool blindly let false negatives slip, problems Claude Code didn’t flag are assumed not to exist.

Automatic review filters noise; it doesn’t guarantee correctness. The human reviewer stays accountable, with less noise, same judgment responsibility.

Operational summary

• CLAUDE.md is foundational: without explicit project rules, review stays generic and low value.
• Custom commands in .claude/commands/review-pr.md define what to check, what to ignore, and output format, less variance between sessions.
• Most sustainable workflow: local review before push, not a mandatory CI gate.
• Claude Code finds explicit rule violations, not business logic or architecture judgment.
• Always read output before acting: false negatives exist and aren’t reported.

Tell us your context, constraints, and goals: we’ll say whether working together makes sense and how to set up a first step.

Email hello@snowinch.com