Rails Idioms

Rails Idioms and Patterns

Rails rewards convention over configuration, Active Record, and RESTful design. Idiomatic Rails = conventional, tested, Hotwire-aware.

Scope: Rails-specific patterns. For Ruby: @.agents/skills/ruby-idioms/SKILL.md.

Active Record

1. Scopes for reusable queries:

   class Task < ApplicationRecord
     scope :active, -> { where(status: :active) }
     scope :by_priority, -> { order(priority: :desc) }
     scope :created_after, ->(date) { where('created_at > ?', date) }
   
     # ✅ Chainable
     # Task.active.by_priority.created_after(1.week.ago)
   end

2. Validations in models, not controllers:

   class Task < ApplicationRecord
     validates :title, presence: true, length: { maximum: 200 }
     validates :priority, inclusion: { in: %w[low medium high] }
   
     # ✅ Custom validation
     validate :deadline_must_be_in_future, on: :create
   
     private
   
     def deadline_must_be_in_future
       return unless deadline.present? && deadline < Time.current
       errors.add(:deadline, 'must be in the future')
     end
   end

3. includes/preload for eager loading — avoid N+1:

   # ❌ N+1 — fires a query per task to load user
   Task.all.each { |t| puts t.user.name }
   
   # ✅ Eager load — 2 queries total
   Task.includes(:user).each { |t| puts t.user.name }
   
   # ✅ Use Bullet gem to detect N+1 in development

4. Callbacks — use sparingly, prefer service objects:

   # ❌ Complex callback chains — hard to test and debug
   before_save :normalize_title, :set_defaults, :notify_assignee
   
   # ✅ Service object — explicit, testable
   class CreateTask
     def call(params)
       task = Task.new(normalize(params))
       task.save!
       NotificationService.notify(task.assignee, task)
       task
     end
   end

Controllers

1. RESTful actions — only standard 7 actions per controller. Custom actions = new controller:

   # ❌ Custom action crammed into TasksController
   def complete; end
   
   # ✅ Dedicated controller
   class TaskCompletionsController < ApplicationController
     def create
       task = Task.find(params[:task_id])
       task.complete!
       redirect_to task
     end
   end

2. Strong parameters — never mass-assign without permit:

   private
   
   def task_params
     params.require(:task).permit(:title, :priority, :deadline, :description)
   end

3. Service objects for complex business logic:

   class TasksController < ApplicationController
     def create
       result = CreateTask.new.call(task_params)
       if result.success?
         redirect_to result.task, notice: 'Task created'
       else
         @task = result.task
         render :new, status: :unprocessable_entity
       end
     end
   end

Error Handling

For universal error handling principles, see .agents/rules/error-handling-principles.md.

1. rescue_from for controller-level error handling:

   class ApplicationController < ActionController::Base
     rescue_from ActiveRecord::RecordNotFound, with: :not_found
     rescue_from ActiveRecord::RecordInvalid, with: :unprocessable
   
     private
   
     def not_found(exception)
       render json: { error: exception.message }, status: :not_found
     end
   
     def unprocessable(exception)
       render json: { errors: exception.record.errors.full_messages },
              status: :unprocessable_entity
     end
   end

2. Custom domain errors:

   module TaskErrors
     class NotAssignable < StandardError; end
     class DeadlinePassed < StandardError; end
   end

3. Never rescue Exception — always rescue StandardError or specific subclasses.

Hotwire (7+)

1. Turbo Frames for partial page updates:

   <!-- Wraps content that can be independently loaded/replaced -->
   <%= turbo_frame_tag "task_#{task.id}" do %>
     <%= render task %>
   <% end %>

2. Turbo Streams for real-time updates:

   # In controller — auto-broadcasts updates
   def create
     @task = Task.create!(task_params)
     respond_to do |format|
       format.turbo_stream
       format.html { redirect_to tasks_path }
     end
   end

3. Stimulus for JavaScript sprinkles — minimal JS.