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:

Priority	Label	Criteria	Action
CRITICAL	Red	Security vulnerabilities, data loss risks, privacy violations, production crashes	Fix immediately
HIGH	Orange	Performance in hot paths, resource leaks, broken error handling, missing validation	Fix before merge
MEDIUM	Yellow	Maintainability issues, inconsistent patterns, missing tests, tech debt in active areas	Fix soon
LOW	Green	Style inconsistencies, minor optimizations, documentation gaps	Fix when convenient

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