RuboCop Code Analysis & Formatting

RuboCop is Ruby's premier static code analyzer (linter) and formatter, based on the community-driven Ruby Style Guide. This skill enables comprehensive code analysis, automatic formatting, and enforcement of coding standards across Ruby projects including Rails applications.

When to Use This Skill

Claude automatically uses this skill when users:

• Ask to "check", "lint", "analyze", or "review" Ruby code
• Request code formatting or style improvements
• Want to enforce coding standards or style guidelines
• Need to detect potential bugs or code smells
• Ask about RuboCop configuration or setup
• Request Rails, RSpec, or performance-specific analysis
• Want to run autocorrections on Ruby code

Core Capabilities

Code Analysis & Linting

• Detects style violations, bugs, and code smells across all cop departments
• Supports Rails, RSpec, Performance, and custom cop extensions
• Provides detailed offense reports with line numbers and descriptions

Automatic Code Correction

• Safe autocorrection (-a) for guaranteed-safe fixes
• Unsafe autocorrection (-A) for broader but riskier corrections
• Layout-only fixes (-x) for formatting without logic changes

Configuration & Customization

• Flexible .rubocop.yml configuration
• Per-project and per-directory configuration inheritance
• Selective cop enabling/disabling and severity adjustment
• Custom cop development support

Extension Integration

• rubocop-rails: Rails best practices and conventions
• rubocop-rspec: RSpec-specific analysis
• rubocop-performance: Performance optimization checks

Quick Analysis Workflow

Run Basic Analysis

# Analyze current directory
rubocop

# Analyze specific files/directories
rubocop app spec lib/important_file.rb

# Show only correctable offenses
rubocop --display-only-correctable

Apply Corrections

# Safe autocorrection only (recommended)
rubocop -a

# All corrections including unsafe
rubocop -A

# Layout/formatting corrections only
rubocop -x

# Autocorrect specific cops
rubocop -a --only Style/StringLiterals,Layout/TrailingWhitespace

Targeted Analysis

# Run only specific cops
rubocop --only Style/StringLiterals,Naming/MethodName

# Run all cops except specified
rubocop --except Metrics/MethodLength

# Run only lint cops
rubocop --lint

# Check only Rails-specific issues
rubocop --only Rails

Configuration Essentials

Basic .rubocop.yml Setup

# Enable extensions
plugins:
  - rubocop-rails
  - rubocop-rspec
  - rubocop-performance

AllCops:
  TargetRubyVersion: 3.2
  NewCops: enable  # Auto-enable new cops
  Exclude:
    - 'db/schema.rb'
    - 'vendor/**/*'
    - 'node_modules/**/*'

# Adjust specific cops
Style/StringLiterals:
  EnforcedStyle: double_quotes

Metrics/MethodLength:
  Max: 15
  Exclude:
    - 'spec/**/*'

Common Configuration Patterns

Inherit from shared config:

inherit_from:
  - .rubocop_todo.yml
  - config/rubocop_defaults.yml

Rails-specific settings:

Rails:
  Enabled: true

Rails/ApplicationRecord:
  Enabled: true
  Exclude:
    - 'db/migrate/**'

RSpec configuration:

RSpec/ExampleLength:
  Max: 10

RSpec/MultipleExpectations:
  Max: 3

Analysis Interpretation

Understanding Offense Output

app/models/user.rb:15:3: C: Style/StringLiterals: Prefer single-quoted strings...
  name = "John Doe"
         ^^^^^^^^^^

Format breakdown:

• app/models/user.rb:15:3 - File path, line number, column number
• C: - Severity (C=Convention, W=Warning, E=Error, F=Fatal)
• Style/StringLiterals - Cop department and name
• Message explains the issue and often suggests fixes

Severity Levels

• Convention (C): Style/formatting issues
• Warning (W): Potential problems that should be reviewed
• Error (E): Definite problems that need fixing
• Fatal (F): Syntax errors preventing analysis

Common Workflows

Initial Project Setup

# Generate initial configuration
rubocop --init

# Generate .rubocop_todo.yml for existing violations
rubocop --auto-gen-config

# Use todo file to gradually fix issues
# .rubocop.yml:
inherit_from: .rubocop_todo.yml

Pre-commit Integration

# Check staged files only
git diff --name-only --cached | grep '\.rb$' | xargs rubocop

# With autocorrection
git diff --name-only --cached | grep '\.rb$' | xargs rubocop -a

CI/CD Integration

# Exit with error code if offenses found
rubocop --format progress --fail-level warning

# Generate formatted reports
rubocop --format json --out rubocop-report.json
rubocop --format html --out rubocop-report.html

Parallel Execution

# Use all available CPUs (enabled by default)
rubocop --parallel

# Limit CPU usage
PARALLEL_PROCESSOR_COUNT=2 rubocop

Extension-Specific Features

Rails Analysis

Detects Rails-specific issues:

• ActiveRecord best practices
• Controller and routing conventions
• Migration safety checks
• SQL injection risks

RSpec Analysis

Enforces RSpec best practices:

• Example organization and naming
• Let vs instance variable usage
• Expectation patterns
• Test file structure

Performance Analysis

Identifies performance optimizations:

• Inefficient collection methods
• String concatenation issues
• Unnecessary array allocations
• Regex compilation optimizations

Troubleshooting

"Unknown cop" errors:

• Ensure required gems are installed (rubocop-rails, rubocop-rspec, etc.)
• Add to .rubocop.yml: plugins: [rubocop-rails]

Autocorrection not working:

• Some cops don't support autocorrection
• Use -A for unsafe corrections
• Check cop is enabled in configuration

Performance issues:

• Use --parallel for faster execution
• Add UseCache: true under AllCops in config
• Exclude large generated files

Additional Resources

• Configuration Guide - Comprehensive configuration reference
• Cop Reference - All cop departments and their responsibilities
• Extensions Guide - Rails, RSpec, Performance extension details
• Autocorrect Guide - Safe vs unsafe corrections explained
• Custom Cops Guide - Creating custom cops for your project