Code Review Patterns

A language-agnostic framework for conducting comprehensive, context-aware code reviews that provide actionable feedback with real-world impact prioritization.

Core Philosophy

Effective code reviews go beyond surface-level issues to understand root causes and systemic patterns. Focus on providing deep, actionable feedback that considers business context, not just technical correctness.

Key principles:

• •Understand project context and conventions before reviewing
• •Provide root cause analysis, not just symptoms
• •Include working solutions with every issue
• •Prioritize by real-world impact
• •Adapt to the language and framework of the codebase

Pre-Review Context Gathering

Before reviewing, establish context from the project itself:

1. •Read project documentation - CLAUDE.md, README, CONTRIBUTING, ARCHITECTURE docs
2. •Detect conventions - Linting configs, formatting rules, existing patterns
3. •Understand structure - Directory layout, module organization, naming conventions
4. •Identify testing patterns - Test framework, assertion style, coverage expectations
5. •Check language/framework - Adapt review criteria to the stack

The codebase itself defines what "good" looks like - discover and apply those standards.

Root Cause Analysis Framework

For every issue, provide three levels of analysis:

Level 1 - What: The immediate issue observed Level 2 - Why: Root cause analysis explaining why this happens Level 3 - How: Specific, actionable solution with working code

This ensures issues are fully understood and solutions address underlying problems, not just symptoms.

Impact-Based Prioritization

Classify every issue by real-world impact:

Prioritization Factors

• •User-facing code → Higher priority than internal utilities
• •Security-sensitive paths (auth, payments, PII) → Highest priority
• •Frequently changed files → Higher priority (high churn = high impact)
• •Hot paths (high traffic) → Performance issues more critical

Six Review Aspects

Comprehensive reviews cover six specialized aspects:

1. •Architecture & Design - Module organization, separation of concerns, design patterns, dependency direction
2. •Code Quality - Readability, naming, complexity, DRY principles, cognitive load
3. •Security & Dependencies - Vulnerabilities, auth, input validation, supply chain
4. •Performance & Scalability - Algorithm complexity, resource usage, async patterns, caching
5. •Testing Quality - Meaningful assertions, isolation, edge cases, maintainability
6. •Documentation & API - Self-documenting code, API docs, breaking changes

For detailed guidance on each aspect, see references/review-aspects.md.

Cross-File Intelligence

Comprehensive review requires understanding relationships:

• •Component → Tests: Is test coverage adequate?
• •Interface → Implementations: Are all implementations consistent?
• •Config → Usage: Do usage patterns align with configuration?
• •Fix → Call sites: Are all callers handled?
• •API change → Documentation: Is documentation updated?

Find related files before concluding a review is complete.

Review Intelligence Layers

Apply five layers of analysis:

1. •Syntax & Style - Follows project's linting/formatting rules
2. •Patterns & Practices - Uses established patterns, avoids anti-patterns
3. •Architectural Alignment - Code in correct layer, proper abstraction level
4. •Business Logic Coherence - Logic matches requirements, edge cases handled
5. •Evolution & Maintenance - How code ages, testability, extensibility

Solution-Oriented Feedback

Never just identify problems - always show the fix. A quality issue report includes:

1. •Issue title with file location
2. •Impact - Real-world consequence
3. •Root cause - Why this happens
4. •Solution - Working code in the project's language/style
5. •Alternatives (optional) - Other valid approaches

Adapt solutions to match the codebase's existing patterns and conventions.

Review Output Template

Structure feedback consistently:

# Code Review: [Scope]

## Review Metrics
- **Files Reviewed**: X
- **Critical Issues**: X
- **High Priority**: X
- **Medium Priority**: X
- **Suggestions**: X

## Executive Summary
[2-3 sentences summarizing the most important findings]

## CRITICAL Issues (Must Fix)
[Issues with root cause analysis and working solutions]

## HIGH Priority (Fix Before Merge)
[Issues with root cause analysis and working solutions]

## MEDIUM Priority (Fix Soon)
[Issues with root cause analysis and working solutions]

## LOW Priority (Opportunities)
[Suggestions and minor improvements]

## Strengths
[What's done well, patterns worth replicating]

## Proactive Suggestions
[Opportunities beyond identified issues]

## Systemic Patterns
[Issues appearing multiple times - candidates for team discussion]

Additional Resources

Reference Files

For detailed patterns and guidance, consult:

• •references/focus-areas.md - Canonical definitions of the 6 focus areas with priority factors
• •references/review-aspects.md - Deep dive into each review aspect with checklists

Success Criteria

A quality review should:

• •Understand project context and conventions first
• •Adapt to the language and framework in use
• •Provide root cause analysis, not just symptoms
• •Include working solutions in the project's style
• •Prioritize by real-world impact
• •Consider evolution and maintenance
• •Reference existing patterns in the codebase