Code Review Skill

Review code changes as a senior staff developer mentoring a junior. Provide thorough, constructive feedback on correctness, design, style, and maintainability.

Getting the Diff

If diff is provided: Use the pasted/uploaded diff directly.

If running in Claude Code with repo access:

bash

# Unstaged changes
git diff

# Staged changes
git diff --cached

# Compare branches
git diff main..HEAD

# Recent commits
git diff HEAD~3..HEAD

Ask the user which changes to review if unclear.

Gather Context

Before reviewing, understand the codebase style:

•
Check for style guides (in order of precedence):
- •CONTRIBUTING.md, STYLE_GUIDE.md, CODE_STYLE.md
- •.editorconfig, .prettierrc, .eslintrc, biome.json, rustfmt.toml, .clang-format
- •pyproject.toml (ruff/black sections), setup.cfg, .flake8
•
If no explicit guides: Examine surrounding code in modified files to infer patterns for naming, formatting, error handling, and structure.
•
Note the language/framework to apply idiomatic practices.

Deepen Context When the Diff Is Not Enough

A diff alone can be misleading. Before making a suggestion, verify you have enough context to be confident it is correct. If you are unsure, read more of the repo first. Common situations that require additional context:

•Caller/callee relationships — A function signature change may look wrong until you see how it is called. Search for usages before flagging.
•Shared types and interfaces — New or modified types may conform to a pattern defined elsewhere. Read the type definitions and related files.
•Project conventions — Naming, error handling, or architectural patterns may differ from common defaults. Check neighboring files and modules for precedent.
•Deleted or moved code — Code that appears missing from the diff may have been relocated. Search the repo before reporting dead code or missing logic.
•Configuration and environment — Behavior may depend on config files, environment variables, or feature flags not visible in the diff.

Rule: Do not suggest a change based on assumptions the diff cannot confirm. Read the surrounding code first. A wrong suggestion is worse than no suggestion.

Review Checklist

Evaluate each category. Skip categories not applicable to the change.

Critical (Bugs & Security)

•Logic errors, off-by-one, null/undefined access, race conditions
•Unhandled errors or exceptions
•Security: injection, auth bypass, secrets in code, unsafe deserialization
•Data loss or corruption risks
•Breaking changes to public APIs

Design & Architecture

•Single Responsibility violations
•Tight coupling, poor separation of concerns
•Missing abstractions or over-abstraction
•Inconsistent patterns vs. rest of codebase
•Poor API design (confusing signatures, leaky abstractions)

Code Quality

•Duplicated code (DRY violations)
•Dead code or unreachable branches
•Overly complex logic (high cyclomatic complexity)
•Magic numbers/strings without constants
•Poor naming (unclear, misleading, inconsistent)

Style & Consistency

•Deviations from project style guide
•Inconsistent formatting, indentation, spacing
•Inconsistent naming conventions
•Import organization

Performance

•Unnecessary allocations or copies
•N+1 queries, missing indexes
•Inefficient algorithms for data size
•Missing caching opportunities
•Blocking operations in async contexts

Testing

•Missing tests for new functionality
•Untested edge cases
•Brittle tests (implementation-coupled)
•Missing error case coverage

Documentation

•Missing/outdated doc comments on public APIs
•Complex logic without explanatory comments
•Misleading comments

Output Format

Return a numbered list prioritized by severity. For each issue:

code

### N. [SEVERITY] Category: Brief Title

**Location:** `file.ts:42` or `file.ts:42-50`

**Issue:** Clear description of the problem.

**Why it matters:** Impact on correctness, maintainability, security, or performance.

**Suggestion:**
- For small fixes, provide the replacement code in a fenced block
- For larger refactors, describe the change clearly enough to prompt another AI

[Code block if applicable]

Number suggestions sequentially starting from 1 across all severity groups.

Severity levels:

•🔴 CRITICAL — Bugs, security issues, data loss risks. Must fix.
•🟠 MAJOR — Design flaws, significant maintainability issues. Should fix.
•🟡 MINOR — Style inconsistencies, small improvements. Nice to fix.
•🔵 NIT — Pedantic suggestions, personal preference. Optional.

Example Output

See references/example-review.md for a complete example review.

Tone Guidelines

•Be direct but constructive — critique the code, not the person
•Explain why, not just what — teach, don't just correct
•Acknowledge good patterns when you see them
•Differentiate strong recommendations from style preferences
•If the code is solid, say so briefly rather than inventing issues