Community Ruby on Rails Development Best Practices

Comprehensive performance and maintainability optimization guide for Ruby on Rails applications, maintained by Community. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Rails controllers, models, or views
• Optimizing ActiveRecord queries and database access patterns
• Implementing caching strategies (fragment, Russian doll, low-level)
• Building or refactoring API endpoints
• Adding Turbo Frames and Streams for interactive UIs
• Reviewing code for N+1 queries and security vulnerabilities
• Designing background jobs with Sidekiq or Active Job
• Writing or reviewing database migrations

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Database & ActiveRecord	CRITICAL	db-
2	Controllers & Routing	CRITICAL	ctrl-
3	Security	HIGH	sec-
4	Models & Business Logic	HIGH	model-
5	Caching & Performance	HIGH	cache-
6	Views & Frontend	MEDIUM-HIGH	view-
7	API Design	MEDIUM	api-
8	Background Jobs & Async	LOW-MEDIUM	job-

Quick Reference

1. Database & ActiveRecord (CRITICAL)

• db-eager-load-associations - Eager load associations to eliminate N+1 queries
• db-add-database-indexes - Add database indexes on queried columns
• db-select-specific-columns - Select only needed columns
• db-batch-processing - Use find_each for large dataset iteration
• db-avoid-queries-in-loops - Avoid database queries inside loops
• db-use-scopes - Define reusable query scopes on models
• db-safe-migrations - Write reversible zero-downtime migrations
• db-exists-over-count - Use exists? instead of count for existence checks

2. Controllers & Routing (CRITICAL)

• ctrl-thin-controllers - Keep controllers thin by delegating to models and services
• ctrl-strong-params - Always use strong parameters for mass assignment
• ctrl-restful-routes - Follow RESTful routing conventions
• ctrl-before-action-scoping - Scope before_action callbacks with only/except
• ctrl-respond-to-format - Use respond_to for multi-format responses
• ctrl-rescue-from - Handle errors with rescue_from in controllers

3. Security (HIGH)

• sec-parameterized-queries - Never interpolate user input in SQL
• sec-strong-params-whitelist - Whitelist permitted params, never blacklist
• sec-authenticate-before-authorize - Authenticate before authorize on every request
• sec-csrf-protection - Enable CSRF protection for all form submissions
• sec-scope-queries-to-user - Scope queries to current user for authorization

4. Models & Business Logic (HIGH)

• model-validate-at-model-level - Validate data at the model level
• model-avoid-callback-side-effects - Avoid side effects in model callbacks
• model-use-service-objects - Extract complex logic into service objects
• model-scope-over-class-methods - Use scopes instead of class methods for query composition
• model-use-enums - Use enums for finite state fields
• model-concerns-for-shared-behavior - Use concerns for shared model behavior
• model-query-objects - Extract complex queries into query objects

5. Caching & Performance (HIGH)

• cache-fragment-caching - Use fragment caching for expensive view partials
• cache-russian-doll - Use Russian doll caching for nested collections
• cache-low-level - Use Rails.cache.fetch for computed data
• cache-counter-cache - Use counter caches for association counts
• cache-conditional-get - Use conditional GET with stale? for HTTP caching

6. Views & Frontend (MEDIUM-HIGH)

• view-collection-rendering - Use collection rendering instead of loop partials
• view-turbo-frames - Use Turbo Frames for partial page updates
• view-turbo-streams - Use Turbo Streams for real-time page mutations
• view-form-with - Use form_with instead of form_tag or form_for
• view-avoid-logic-in-views - Move display logic to helpers or presenters

7. API Design (MEDIUM)

• api-serializers - Use serializers for consistent JSON responses
• api-pagination - Always paginate collection endpoints
• api-versioning - Version APIs from day one
• api-error-responses - Return structured error responses
• api-avoid-jbuilder-hot-paths - Avoid Jbuilder on high-traffic endpoints

8. Background Jobs & Async (LOW-MEDIUM)

• job-idempotent-design - Design jobs to be idempotent
• job-small-payloads - Pass IDs to jobs, not serialized objects
• job-error-handling - Configure retry and error handling for jobs
• job-unique-jobs - Prevent duplicate job enqueuing

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information