Claude Code Review Workflow
Claude Code's /review command gives every PR a structured first-pass review before a human reviewer sees it. Unlike lint or static analysis, Claude reads the full codebase — it understands how the changed code fits into the broader system, which lets it catch integration bugs, missing auth checks, and architectural drift that file-scoped tools miss entirely.
The /review Command
The fastest way to review your current changes:
# Review all uncommitted changes /review # Review a specific file /review src/auth/login.ts # Review the diff between your branch and main /review --diff main # Review a GitHub PR (requires gh CLI) /review --pr 342
Claude reads the diff, the surrounding files, and your CLAUDE.md conventions before generating the review. Output is structured by severity: Critical (bugs/security), Warning (missing error handling, performance), Info (style, naming, readability).
/review focus on security issues only or /review ignore style, focus on correctness and test coverage. Without scope, Claude reviews everything — useful for thoroughness, noisy for style-consistent codebases.Manual Review Workflow (No /review Command)
If you prefer a conversational approach, paste the diff directly:
Here's the diff for PR #342 (adds payment webhook handler):
[paste git diff output]
Review it for: (1) security issues — auth checks, input validation, secret handling, (2) error handling — what happens if Stripe sends a malformed payload?, (3) idempotency — can the webhook fire twice and cause a double-charge?, (4) test coverage — are edge cases covered? Focus on correctness; ignore style.
The explicit scope ("focus on correctness; ignore style") is load-bearing — without it, Claude spends review capacity on variable names instead of logic correctness.
What Claude Reviews For
| Category | What Claude catches |
|---|---|
| Logic bugs | Off-by-one errors, wrong conditional direction, missed edge cases, null pointer paths |
| Security | SQL injection, XSS, missing auth checks, exposed secrets, IDOR, insecure deserialization |
| Error handling | Unhandled promise rejections, swallowed exceptions, missing status codes |
| Performance | N+1 queries, missing indexes, unnecessary re-renders, synchronous I/O in hot paths |
| Test gaps | Untested error paths, missing edge cases, tests that assert on implementation not behavior |
| Architecture | Layering violations, circular dependencies, leaking domain logic into controllers |
| Conventions | Whatever is in your CLAUDE.md — commit style, naming rules, forbidden patterns |
GitHub Actions Integration
Automate a Claude review on every pull request. Add this workflow to .github/workflows/claude-review.yml:
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run Claude Review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
REVIEW=$(claude /review --diff origin/main --output markdown 2>&1)
gh pr comment ${{ github.event.pull_request.number }} \
--body "## Claude Code Review
$REVIEW
---
*Automated review by Claude Code — not a substitute for human review.*"
Self-Review Before Committing
The highest-value use is reviewing your own code before pushing. Run /review on your staged changes and let Claude catch what you missed:
I'm about to commit these changes. Review them as if you were a senior engineer on this team. Flag anything that would get a "request changes" in a real PR — bugs, missing tests, security issues, or things that violate our CLAUDE.md conventions. Be direct.
"Be direct" is the important instruction here. Without it, Claude softens findings into suggestions. A pre-commit self-review takes 30 seconds and regularly catches issues that would have taken an hour to debug post-merge.
Team Review Workflow
In team settings, Claude review works best as a first-pass filter, not a replacement for human review:
- Author self-reviews before opening the PR — catches obvious issues before reviewers are looped in
- Automated CI review runs on PR open — gives reviewers a structured overview of the diff
- Human reviewer focuses on product correctness, architecture, and team knowledge — things Claude can't assess
- Pre-merge final check — after requested changes are made, re-run
/reviewto confirm nothing was accidentally broken
Focused Review Types
Security review
Security review of this PR only. Check: authentication/authorization on every new route, input validation and sanitization, SQL query construction (parameterized?), any secrets or credentials in code, and error messages that might leak implementation details. Ignore style and performance.
Database migration review
Review this database migration. Check: is it reversible (down migration provided)?, does it lock the table for writes during execution?, is there a data backfill needed for existing rows?, does it break any existing queries or ORM models?, is it safe to run against a live production database with the table at current scale?
API change review
Review this API change for backwards compatibility. Check: are existing API clients broken?, are required fields added without defaults?, are response shapes changed in a non-additive way?, is the version bump correct if this is a breaking change?
FAQ
How do I use the /review command in Claude Code?
Run /review with no arguments to review all uncommitted changes, or pass a file path to review a specific file: /review src/auth/login.ts. Claude reads the diff, the surrounding codebase context, and your CLAUDE.md conventions before generating the review. It flags bugs, security issues, style violations, and missing tests — not just style nits.
Can Claude Code review a GitHub pull request?
Yes. Run claude /review --pr <PR-number> in a repo with GitHub CLI installed, or paste the output of git diff main...HEAD directly into a Claude Code conversation. For automated PR review on every push, add a GitHub Actions step that runs Claude review and posts the result as a PR comment using the GitHub API.
What does Claude Code look for in a code review?
Claude reviews for logic bugs, security issues, missing error handling, performance problems, test coverage gaps, naming and readability, and violations of your CLAUDE.md conventions. You can focus the review by adding scope instructions: "focus on security" or "ignore style issues, focus on correctness only."
How is Claude Code review different from GitHub Copilot review?
Claude Code reads your full codebase before reviewing — it understands how the changed code fits into the broader system, catching integration bugs and architectural drift that file-scoped tools miss. GitHub Copilot review operates at the file level; Claude Code gives a structured review with severity levels and cross-file context.
Can I automate Claude Code review in CI?
Yes. Add a GitHub Actions workflow that triggers on pull_request events, checks out the repo, installs Claude Code, runs claude /review --output markdown, and posts the result as a PR comment. Set ANTHROPIC_API_KEY as a repository secret. This gives every PR an automatic first-pass review before human reviewers see it.