rails-dev-guidelines

Rails MVC patterns, ActiveRecord, conventions, and best practices

⭐7stars🔀1forks📁View on GitHub🕐Updated Nov 19, 2025

When & Why to Use This Skill

This Claude skill provides comprehensive guidelines for Ruby on Rails development, focusing on MVC architecture, ActiveRecord best practices, and idiomatic conventions. It ensures the creation of maintainable, secure, and high-performance Rails applications by enforcing 'Fat Models, Skinny Controllers' patterns, service object extraction, and N+1 query prevention. It serves as a definitive style guide for building scalable web applications following the 'Rails Way'.

Use Cases

  • Architecting new Rails components: Use the skill to ensure models, controllers, and migrations follow strict naming conventions and standard directory structures.
  • Refactoring legacy code: Extract complex business logic from bloated controllers into dedicated Service Objects or Query Objects to improve code maintainability and testability.
  • Database performance optimization: Identify and resolve N+1 query issues by implementing eager loading and adding necessary database-level constraints and indexes.
  • Security and validation enforcement: Implement robust data protection using Strong Parameters and multi-layered validations at both the model and database levels.
namerails-dev-guidelines
descriptionRails MVC patterns, ActiveRecord, conventions, and best practices

Rails Development Guidelines

Purpose

This skill ensures consistent, maintainable Rails code following conventions and best practices for the application.

When to Use This Skill

  • Creating or modifying models, controllers, or other Rails components
  • Implementing business logic or data access patterns
  • Working with ActiveRecord associations, validations, or queries
  • Creating migrations or modifying the database schema
  • Implementing background jobs or service objects
  • Following Rails conventions and idiomatic patterns

Core Rails Conventions

Directory Structure

app/
├── models/          # Business logic and data models
├── components/      # View components (ViewComponent gem)
├── controllers/     # Request handling and response rendering
├── views/           # Templates (ERB, Turbo)
├── helpers/         # View helpers
├── jobs/            # Background jobs
├── mailers/         # Email sending
├── services/        # Complex business logic
├── queries/         # Complex database queries
├── forms/           # Form objects for complex forms
└── concerns/        # Shared modules (models & controllers)

Model Development Checklist

When creating or modifying a model:

  • Use singular name (e.g., User, not Users)
  • Place validations before associations and callbacks
  • Use database-level constraints with migrations
  • Add indexes for foreign keys and frequently queried columns
  • Use scopes for reusable queries
  • Keep concerns in app/models/concerns/
  • Write comprehensive model specs with factories

Controller Development Checklist

When creating or modifying a controller:

  • Use RESTful routes when possible
  • Keep actions thin (extract to services/queries)
  • Use strong parameters (params.require().permit())
  • Set instance variables only for view data
  • Use before_action for authentication/authorization
  • Handle errors with rescue_from or inline rescues
  • Write request specs for all endpoints

Core Principles

1. Fat Models, Skinny Controllers

❌ Don't put business logic in controllers:

# app/controllers/users_controller.rb
def create
  @user = User.new(user_params)
  @user.email = params[:email].downcase
  @user.role = 'member'
  @user.save

  UserMailer.welcome_email(@user).deliver_later
  Analytics.track_signup(@user)

  redirect_to @user
end

✅ Do move logic to models or services:

# app/controllers/users_controller.rb
def create
  @user = User.create_with_defaults(user_params)

  if @user.persisted?
    redirect_to @user, notice: 'Welcome!'
  else
    render :new, status: :unprocessable_entity
  end
end

# app/models/user.rb
class User < ApplicationRecord
  after_create :send_welcome_email
  after_create :track_signup

  def self.create_with_defaults(params)
    user = new(params)
    user.email = user.email.downcase
    user.role ||= 'member'
    user.save
    user
  end

  private

  def send_welcome_email
    UserMailer.welcome_email(self).deliver_later
  end

  def track_signup
    Analytics.track_signup(self)
  end
end

2. Use Service Objects for Complex Operations

❌ Don't cram complex workflows into models:

class Order < ApplicationRecord
  def process_payment
    # 50+ lines of payment processing logic
  end
end

✅ Do extract to service objects:

# app/services/order_processor.rb
class OrderProcessor
  def initialize(order)
    @order = order
  end

  def process
    return false unless valid?

    ActiveRecord::Base.transaction do
      charge_payment
      update_inventory
      send_confirmation
    end

    true
  rescue PaymentError => e
    @order.errors.add(:base, e.message)
    false
  end

  private

  def valid?
    @order.valid? && @order.items.any?
  end

  # ... more private methods
end

3. Strong Parameters Are Required

❌ Don't use raw params:

def create
  User.create(params[:user])  # Security vulnerability!
end

✅ Do use strong parameters:

def create
  @user = User.new(user_params)
  # ...
end

private

def user_params
  params.require(:user).permit(:email, :name, :role)
end

4. Use Database Constraints

❌ Don't rely only on ActiveRecord validations:

# app/models/user.rb
validates :email, uniqueness: true

✅ Do add database constraints too:

# db/migrate/xxx_create_users.rb
create_table :users do |t|
  t.string :email, null: false
  t.timestamps
end

add_index :users, :email, unique: true

# app/models/user.rb
validates :email, presence: true, uniqueness: true

5. Avoid N+1 Queries

❌ Don't lazy load associations in loops:

@users = User.all
@users.each do |user|
  puts user.posts.count  # N+1 query!
end

✅ Do eager load associations:

@users = User.includes(:posts).all
@users.each do |user|
  puts user.posts.count  # No extra queries
end

Anti-Patterns

❌ Don't Use Callbacks for Business Logic

Callbacks make models hard to test and reason about. Use service objects instead.

❌ Don't Skip Validations

Never use save(validate: false) or update_column unless absolutely necessary.

❌ Don't Put SQL in Controllers

Extract complex queries to query objects or scopes.

❌ Don't Use find_by_sql Without Reason

Use ActiveRecord query interface when possible.

❌ Don't Expose Internal IDs

Use slugs or UUIDs for public-facing URLs.

Quick Reference: Common Patterns

Associations

belongs_to :user
has_many :posts
has_many :comments, through: :posts
has_one :profile, dependent: :destroy

Validations

validates :email, presence: true, uniqueness: true, format: { with: URI::MailTo::EMAIL_REGEXP }
validates :age, numericality: { greater_than: 18 }
validates :terms, acceptance: true

Scopes

scope :active, -> { where(active: true) }
scope :recent, -> { order(created_at: :desc).limit(10) }
scope :by_role, ->(role) { where(role: role) }

Callbacks (Use Sparingly)

before_validation :normalize_email
after_create :send_notification
after_destroy :cleanup_associated_data

Need help with:

  • ActiveRecord Associations → See resources/associations.md
  • Validations & Constraints → See resources/validations.md
  • Query Optimization → See resources/queries.md
  • Service Objects Pattern → See resources/service-objects.md
  • Background Jobs → See resources/background-jobs.md
  • Security Best Practices → See resources/security.md

Resource Files

  1. associations.md - Detailed guide on ActiveRecord associations
  2. validations.md - Validation patterns and database constraints
  3. queries.md - Query optimization and avoiding N+1 queries
  4. service-objects.md - Service object patterns for complex logic
  5. background-jobs.md - Solid Queue and background job patterns
  6. security.md - Security best practices for Rails
  • rspec-testing-guidelines - For writing comprehensive tests
  • devise-auth-patterns - For authentication implementation
  • database-design-patterns - For schema design and migrations
  • security-best-practices - For security concerns

Status: Core skill (~450 lines) | 6 resource files