RubyCritic Code Quality Analysis Skill
A Claude Code skill for analyzing Ruby and Rails code quality using RubyCritic.
Description
This skill integrates RubyCritic to provide comprehensive code quality analysis for Ruby and Rails projects. It helps identify code smells, complexity issues, and areas for refactoring with detailed metrics and actionable insights.
Commands
/rubycritic [path]
Analyze code quality for the specified path or entire project.
Options:
path(optional): Specific file or directory to analyze. Defaults to current directory.
Examples:
/rubycritic
/rubycritic app/models
/rubycritic app/controllers/users_controller.rb
/rubycritic-summary
Get a quick summary of code quality metrics without detailed file breakdowns.
/rubycritic-worst
Show only the worst-rated files that need immediate attention.
Options:
--limit N: Number of worst files to show (default: 10)
Examples:
/rubycritic-worst
/rubycritic-worst --limit 5
/rubycritic-compare [branch]
Compare code quality between current branch and specified branch.
Options:
branch: Branch to compare against (default: main/master)
Examples:
/rubycritic-compare main
/rubycritic-compare develop
Usage Guidelines
When to Use This Skill
- Before Code Reviews: Run analysis on changed files to catch issues early
- After Refactoring: Verify improvements in code quality metrics
- Regular Health Checks: Weekly or sprint-based quality assessments
- Legacy Code: Identify technical debt and prioritize refactoring efforts
- Onboarding: Help new developers understand code quality standards
Interpretation of Results
Score Ranges:
- A (90-100): Excellent - minimal issues
- B (80-89): Good - minor improvements needed
- C (70-79): Fair - consider refactoring
- D (60-69): Poor - refactoring recommended
- F (<60): Critical - immediate attention required
Key Metrics:
- Churn: How frequently files change (high churn + low quality = priority)
- Complexity: Cyclomatic complexity (aim for < 10 per method)
- Duplication: Code duplication percentage (aim for < 5%)
- Smells: Code smell count by type (Long Method, Feature Envy, etc.)
Best Practices
- Focus on Trends: Track quality over time, not just absolute scores
- Prioritize High-Churn Files: Files that change often with low quality scores
- Set Team Standards: Define acceptable thresholds for your team
- Incremental Improvements: Don't try to fix everything at once
- Context Matters: Some low scores may be acceptable (e.g., configuration files)
Implementation
Installation
The skill automatically checks for RubyCritic and installs it if needed:
gem install rubycritic
Configuration
Create a .rubycritic.yml in your project root for custom settings:
# Minimum score for a file to be considered acceptable
minimum_score: 80.0
# Paths to exclude from analysis
paths:
- 'db/schema.rb'
- 'db/migrate/**/*'
- 'config/**/*'
- 'bin/**/*'
- 'spec/factories/**/*'
# Enable/disable specific analyzers
analyzers:
- flay # Structural duplication
- flog # ABC complexity
- reek # Code smells
- rubocop # Style issues (if available)
# Format for output
formats:
- console
- html
# Branch for comparison mode
branch: main
Output
The skill provides:
- Summary Statistics: Overall project health
- File-Level Scores: Detailed breakdown by file
- Code Smells: Specific issues identified
- Complexity Metrics: Cyclomatic complexity by method
- Recommendations: Actionable suggestions for improvement
Integration with Rails Workflows
Pre-Commit Analysis:
/rubycritic $(git diff --name-only --cached | grep '\.rb$')
CI/CD Integration:
- Run on pull requests to track quality trends
- Fail builds if quality drops below threshold
- Generate HTML reports for team review
Performance Considerations:
- Large projects may take time to analyze
- Use targeted paths for faster feedback
- Run full analysis periodically (CI/CD)
- Cache results when possible
Common Issues and Solutions
Issue: Analysis Takes Too Long
Solution: Narrow the scope
/rubycritic app/models/user.rb
/rubycritic app/controllers
Issue: Too Many False Positives
Solution: Configure .rubycritic.yml to exclude problematic analyzers or paths
Issue: Scores Seem Inconsistent
Solution: RubyCritic uses multiple analyzers; check individual metric breakdowns
Advanced Usage
Custom Thresholds
Set quality gates for your team:
# In your CI/CD pipeline
if average_score < 75
puts "Code quality below threshold!"
exit 1
end
Focused Refactoring
Target specific code smells:
/rubycritic app/models --smells "LongMethod,FeatureEnvy"
Historical Tracking
Compare against previous commits:
/rubycritic-compare HEAD~5
Rails-Specific Considerations
- Models: Pay attention to complexity in callbacks and validations
- Controllers: Watch for fat controllers (complexity > 10)
- Services: Service objects should have low complexity
- Concerns: Check for proper modularity and single responsibility
- Helpers: Avoid business logic in helpers
Output Example
RubyCritic Analysis Results
===========================
Project Score: B (82.5)
Top Issues:
1. app/models/user.rb (Score: 65.2, Grade: D)
- Long Method: #calculate_permissions (complexity: 18)
- Feature Envy: accessing order.items repeatedly
- Duplication: 3 similar conditional blocks
2. app/controllers/orders_controller.rb (Score: 71.3, Grade: C)
- Long Method: #create (complexity: 15)
- Too Many Instance Variables: 6 ivars in #index
Recommendations:
- Extract #calculate_permissions into a service object
- Use Law of Demeter for order.items access
- Refactor conditional logic in User model
- Slim down OrdersController#create method
Resources
Tips for Claude Code
When using this skill, Claude should:
- Provide Context: Explain why certain scores matter
- Prioritize Issues: Focus on high-impact, high-churn files
- Suggest Refactorings: Offer specific code improvements
- Show Examples: Demonstrate better patterns for identified issues
- Track Progress: Help monitor quality improvements over time
- Be Pragmatic: Recognize when "perfect" scores aren't necessary