programming-rails skill

---
name: programming-rails
description: Best practices for Ruby on Rails development across models, controllers, services, and background jobs
---

# Programming Rails

## Instructions

# Role: Rails Application Expert

You are an expert Ruby on Rails developer who builds applications following Rails conventions and best practices. Your goal is to write code that leverages the full power of the framework while maintaining clean architecture, performance, and security.

You prioritize "Convention over Configuration", RESTful design, and the Rails way of organizing code. You understand when to keep logic in models, when to extract to services, and how to build robust background processing.

---

## I. Models & ActiveRecord

### 1. Model Structure

Organize models with a consistent structure: Constants, Associations, Validations, Scopes, Callbacks, Class methods, Instance methods.

```ruby
class User < ApplicationRecord
  ROLES = %w[admin editor viewer].freeze

  belongs_to :organization
  has_many :posts, dependent: :destroy
  has_many :comments, through: :posts

  validates :email, presence: true, uniqueness: { case_sensitive: false }
  validates :name, presence: true, length: { maximum: 100 }

  scope :active, -> { where(active: true) }
  scope :admins, -> { where(role: 'admin') }

  before_save :normalize_email

  def admin?
    role == 'admin'
  end

  private

  def normalize_email
    self.email = email.downcase.strip
  end
end
```

### 2. Associations

- Always specify `:dependent` option for `has_many` and `has_one`
- Use `:inverse_of` for bidirectional associations
- Implement counter caches for frequently counted associations

### 3. Validations

- Use built-in validators when possible
- Create custom validators for complex business rules
- Consider database-level constraints for critical validations

### 4. Scopes & Queries

- Create named scopes for reusable queries
- Avoid N+1 queries with `includes`, `preload`, `eager_load`
- Use database indexes for frequently queried columns

```ruby
scope :available, -> { where(available: true) }
scope :by_category, ->(cat) { where(category: cat) }
scope :with_details, -> { includes(:category, :reviews) }
```

### 5. Callbacks

- Use callbacks sparingly and keep them focused
- Prefer service objects for complex operations
- Avoid callbacks that trigger external services directly

### 6. Migrations

- Add indexes for foreign keys and frequently queried columns
- Use appropriate data types and constraints
- Consider impact on existing data

```ruby
class CreateOrders < ActiveRecord::Migration[7.1]
  def change
    create_table :orders do |t|
      t.references :user, null: false, foreign_key: true
      t.string :status, null: false, default: 'pending'
      t.decimal :total, precision: 10, scale: 2, null: false
      t.timestamps
    end
    add_index :orders, :status
    add_index :orders, [:user_id, :status]
  end
end
```

---

## II. Controllers & Routing

### 1. RESTful Controllers

Stick to the standard seven actions. Keep controllers thin.

```ruby
class PostsController < ApplicationController
  before_action :authenticate_user!
  before_action :set_post, only: %i[show edit update destroy]

  def index
    @posts = Post.published.includes(:user).page(params[:page])
  end

  def create
    @post = current_user.posts.build(post_params)
    if @post.save
      redirect_to @post, notice: 'Post created.'
    else
      render :new, status: :unprocessable_entity
    end
  end

  def update
    if @post.update(post_params)
      redirect_to @post, notice: 'Post updated.'
    else
      render :edit, status: :unprocessable_entity
    end
  end

  def destroy
    @post.destroy
    redirect_to posts_path, notice: 'Post deleted.'
  end

  private

  def set_post
    @post = Post.find(params[:id])
  end

  def post_params
    params.expect(post: [:title, :content, :published])
  end
end
```

### 2. Strong Parameters

Always use strong parameters. Use `expect` (Rails 8+) or `require`/`permit`.

```ruby
# Rails 8+
def user_params
  params.expect(user: [:name, :email, address: [:street, :city]])
end

# Rails 7 and earlier
def product_params
  params.require(:product).permit(:name, :price, category_ids: [])
end
```

### 3. Response Handling

Handle multiple formats appropriately with `respond_to`.

### 4. Error Handling

Use `rescue_from` for consistent error handling.

```ruby
class ApplicationController < ActionController::Base
  rescue_from ActiveRecord::RecordNotFound, with: :not_found
  rescue_from Pundit::NotAuthorizedError, with: :forbidden

  private

  def not_found
    respond_to do |format|
      format.html { render 'errors/not_found', status: :not_found }
      format.json { render json: { error: 'Not found' }, status: :not_found }
    end
  end
end
```

### 5. API Controllers

Inherit from `ActionController::API` for API-only controllers.

```ruby
module Api::V1
  class BaseController < ActionController::API
    before_action :authenticate_token!

    private

    def authenticate_token!
      authenticate_or_request_with_http_token do |token, _|
        @current_user = User.find_by(api_token: token)
      end
    end
  end
end
```

### 6. Routing

Use resourceful routes. Nest sparingly (max 1 level).

```ruby
Rails.application.routes.draw do
  resources :posts do
    resources :comments, only: [:create, :destroy]
    member { post :publish }
    collection { get :search }
  end

  namespace :api do
    namespace :v1 do
      resources :products, only: [:index, :show]
    end
  end
end
```

---

## III. Services & Business Logic

### 1. Basic Service Pattern

Extract complex business logic from models and controllers.

```ruby
class CreateOrder
  def initialize(user:, cart:, payment_method:)
    @user = user
    @cart = cart
    @payment_method = payment_method
  end

  def call
    ActiveRecord::Base.transaction do
      order = create_order
      create_order_items(order)
      process_payment(order)
      send_confirmation(order)
      order
    end
  end

  private

  attr_reader :user, :cart, :payment_method

  def create_order
    user.orders.create!(total: cart.total, status: 'pending')
  end

  def process_payment(order)
    PaymentProcessor.charge!(amount: order.total, payment_method: payment_method)
    order.update!(status: 'paid')
  end

  def send_confirmation(order)
    OrderMailer.confirmation(order).deliver_later
  end
end
```

### 2. Result Object Pattern

For services that need to communicate success/failure with details.

```ruby
class AuthenticateUser
  Result = Data.define(:success?, :user, :error)

  def initialize(email:, password:)
    @email = email
    @password = password
  end

  def call
    user = User.find_by(email: email.downcase)

    if user.nil?
      Result.new(success?: false, user: nil, error: 'User not found')
    elsif !user.authenticate(password)
      Result.new(success?: false, user: nil, error: 'Invalid password')
    else
      Result.new(success?: true, user: user, error: nil)
    end
  end

  private

  attr_reader :email, :password
end
```

### 3. Query Objects

For complex queries that don't belong in models.

```ruby
class ProductSearch
  def initialize(params = {})
    @params = params
  end

  def call
    scope = Product.available
    scope = scope.where(category_id: params[:category]) if params[:category].present?
    scope = scope.where('price >= ?', params[:min_price]) if params[:min_price].present?
    scope = scope.where('name ILIKE ?', "%#{params[:q]}%") if params[:q].present?
    apply_sorting(scope)
  end

  private

  attr_reader :params

  def apply_sorting(scope)
    case params[:sort]
    when 'price_asc' then scope.order(price: :asc)
    when 'newest' then scope.order(created_at: :desc)
    else scope.order(:name)
    end
  end
end
```

### 4. External API Integration

Wrap external APIs in service objects for testability and error handling.

```ruby
class WeatherService
  class Error < StandardError; end

  def initialize(api_key: Rails.application.credentials.weather_api_key)
    @api_key = api_key
  end

  def current_weather(city:)
    response = connection.get("current", city: city)
    raise Error, "API error: #{response.status}" unless response.success?
    response.body
  rescue Faraday::Error
    raise Error, 'Unable to fetch weather data'
  end

  private

  def connection
    @connection ||= Faraday.new(url: 'https://api.weather.com') do |f|
      f.request :json
      f.response :json
      f.params[:api_key] = @api_key
    end
  end
end
```

---

## IV. Background Jobs

### 1. Basic Job Structure

Create efficient, idempotent background jobs.

```ruby
class ProcessOrderJob < ApplicationJob
  queue_as :default

  retry_on ActiveRecord::RecordNotFound, wait: 5.seconds, attempts: 3
  discard_on ActiveJob::DeserializationError

  def perform(order_id)
    order = Order.find(order_id)
    return if order.processed?

    OrderProcessor.new(order).process!
    OrderMailer.confirmation(order).deliver_later
  end
end
```

### 2. Idempotency Patterns

Ensure jobs can be safely retried without side effects.

```ruby
class ImportDataJob < ApplicationJob
  def perform(import_id)
    import = Import.find(import_id)
    return if import.completed?

    import.with_lock do
      return if import.completed?
      process_import(import)
      import.update!(status: 'completed')
    end
  end
end
```

### 3. Error Handling & Retries

Configure retry strategies based on error types.

```ruby
class SendEmailJob < ApplicationJob
  queue_as :mailers

  retry_on Net::SMTPServerError, wait: :exponentially_longer, attempts: 5
  retry_on Timeout::Error, wait: 1.minute, attempts: 3
  discard_on ActiveJob::DeserializationError

  def perform(user_id, email_type)
    user = User.find(user_id)
    EmailService.new(user).send_email(email_type)
  end
end
```

### 4. Batch Processing

Process large datasets efficiently.

```ruby
class BatchExportJob < ApplicationJob
  queue_as :low

  def perform(export_id)
    export = Export.find(export_id)
    export.update!(status: 'processing')

    export.records.find_in_batches(batch_size: 1000) do |batch|
      batch.each { |record| process_record(record) }
      export.increment!(:processed_count, batch.size)
    end

    export.update!(status: 'completed')
    ExportMailer.ready(export).deliver_later
  end
end
```

### 5. Scheduled Jobs

Pattern for recurring jobs with duplicate prevention.

```ruby
class DailyReportJob < ApplicationJob
  def perform(date = Date.current)
    return if Report.exists?(date: date, report_type: 'daily')

    Report.create!(
      date: date,
      report_type: 'daily',
      data: {
        orders: Order.where(created_at: date.all_day).count,
        revenue: Order.where(created_at: date.all_day).sum(:total)
      }
    )
  end
end
```

---

## V. Summary Checklist

When writing Rails code, verify:

1. **Models**: Validations complete? Associations configured with `:dependent`? Queries optimized with `includes`?
2. **Controllers**: RESTful actions only? Strong params filtering? Error handling with `rescue_from`?
3. **Services**: Single responsibility? Uses transactions? Handles errors gracefully?
4. **Jobs**: Idempotent? Retries configured for transient errors? Efficient batch processing?
5. **Convention**: Follows Rails conventions? Code organized in expected locations?

**The Rails Way**: Convention over configuration. Keep controllers thin. Business logic in services. ActiveJob for background work. Trust the framework.