Ruby on Rails Guide

Applies to: Rails 7+, Ruby 3.2+, Hotwire/Turbo, ActiveRecord, Action Cable

Core Principles

Convention over Configuration: Follow Rails conventions -- naming, directory structure, RESTful routes
Fat Models, Thin Controllers: Business logic in models and service objects, controllers handle request/response only
DRY: Use concerns, partials, helpers, and shared services to avoid repetition
RESTful by Default: Design resources around standard CRUD actions before adding custom routes
Security by Default: CSRF, XSS protection, strong parameters, and parameterized queries are built in

When to Use Rails

Good fit: Full-stack web apps, MVPs, CMS, e-commerce, SaaS, Hotwire/Turbo SPA-like UX, API backends.

Consider alternatives: Minimal microservices (Sinatra, Hanami), heavy real-time streaming, strict type safety needs (Rust, Go).

Project Structure

myapp/
├── app/
│   ├── controllers/
│   │   ├── application_controller.rb
│   │   ├── concerns/              # Controller concerns (auth, pagination)
│   │   └── api/
│   │       └── v1/                # Versioned API controllers
│   ├── models/
│   │   ├── application_record.rb
│   │   └── concerns/              # Model concerns (searchable, sluggable)
│   ├── views/
│   │   ├── layouts/               # Application layouts
│   │   │   └── application.html.erb
│   │   ├── shared/                # Shared partials (_navbar, _footer)
│   │   └── posts/                 # Resource-specific views
│   ├── helpers/                   # View helpers
│   ├── jobs/                      # ActiveJob classes
│   ├── mailers/                   # Action Mailer classes
│   ├── channels/                  # Action Cable channels
│   └── services/                  # Service objects (custom directory)
├── config/
│   ├── routes.rb                  # Route definitions
│   ├── database.yml               # Database configuration
│   ├── environments/              # Per-environment settings
│   └── initializers/              # Boot-time configuration
├── db/
│   ├── migrate/                   # Migration files
│   ├── schema.rb                  # Current schema snapshot
│   └── seeds.rb                   # Seed data
├── lib/
│   └── tasks/                     # Custom Rake tasks
├── test/                          # Minitest (default) or spec/ for RSpec
│   ├── models/
│   ├── controllers/
│   ├── integration/
│   └── system/
├── Gemfile
└── Gemfile.lock

Place business logic in
```
app/services/
```
; use concerns for shared model/controller behavior
Namespace API controllers under
```
Api::V1
```
; keep shared partials in
```
views/shared/
```

Guardrails

Controllers

Keep controllers under 100 lines total
Limit each action to 10 lines (delegate to services for complex logic)
Always use
```
before_action
```
for authentication and resource loading
Always use strong parameters via private
```
*_params
```
methods
Return
```
status: :unprocessable_entity
```
for failed form submissions
Use
```
status: :see_other
```
(303) for
```
redirect_to
```
after DELETE
Use
```
respond_to
```
blocks when serving multiple formats

Models

Always add validations for required fields and constraints
Always add
```
dependent:
```
option on
```
has_many
```
/
```
has_one
```
associations
Use
```
scope
```
for reusable queries (never build queries in controllers)
Use
```
enum
```
with explicit integer or string mappings
Use
```
before_validation
```
for data normalization (downcase, strip)
Avoid heavy logic in callbacks -- prefer service objects for side effects
Always define
```
counter_cache: true
```
for belongs_to when parent displays counts

Migrations

Always add
```
null: false
```
for required columns
Always add database indexes for foreign keys and frequently queried columns
Always add unique indexes where uniqueness is required
Use
```
references
```
with
```
foreign_key: true
```
for associations
Set sensible defaults with
```
default:
```
for boolean and status columns
Include both
```
up
```
and
```
down
```
methods for irreversible migrations
Never modify a migration after it has been applied to production

Security

Strong parameters: never use
```
params.permit!
```
(permit all)
CSRF protection: enabled by default, skip only for API controllers with token auth
SQL injection: use ActiveRecord query methods, never string interpolation in queries
XSS: ERB auto-escapes by default; never use
```
raw
```
or
```
html_safe
```
with user data
Mass assignment: only permit explicitly needed attributes
Secrets: use
```
Rails.application.credentials
```
or environment variables
Set
```
force_ssl
```
in production
Use
```
content_security_policy
```
configuration in production

Performance

Always use
```
includes
```
(or
```
preload
```
/
```
eager_load
```
) to prevent N+1 queries
Add database indexes for all foreign keys and commonly filtered columns
Use
```
counter_cache
```
for association counts displayed in views
Use pagination for all list endpoints (Kaminari or Pagy)
Use fragment caching (
```
cache @record do
```
) for expensive view rendering
Use background jobs (ActiveJob + Sidekiq) for slow operations
Use
```
find_each
```
instead of
```
each
```
when iterating over large datasets

MVC Conventions

Models

ruby

# app/models/post.rb
class Post < ApplicationRecord
  # 1. Associations
  belongs_to :user
  belongs_to :category, optional: true
  has_many :comments, dependent: :destroy
  has_many :taggings, dependent: :destroy
  has_many :tags, through: :taggings
  has_one_attached :featured_image

  # 2. Validations
  validates :title, presence: true, length: { maximum: 255 }
  validates :body, presence: true

  # 3. Enums
  enum :status, { draft: 0, published: 1, archived: 2 }

  # 4. Scopes
  scope :published, -> { where(status: :published) }
  scope :recent, -> { order(created_at: :desc) }
  scope :by_category, ->(cat) { where(category: cat) }
  scope :search, ->(q) {
    where("title ILIKE :q OR body ILIKE :q", q: "%#{sanitize_sql_like(q)}%")
  }

  # 5. Callbacks (keep minimal)
  before_validation :normalize_title

  # 6. Instance methods
  def publish!
    update!(status: :published, published_at: Time.current)
  end

  private

  def normalize_title
    self.title = title&.strip
  end
end

Model ordering convention: Associations, validations, enums, scopes, callbacks, class methods, instance methods, private methods.

Controllers

ruby

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  before_action :authenticate_user!, except: [:index, :show]
  before_action :set_post, only: [:show, :edit, :update, :destroy]
  before_action :authorize_post!, only: [:edit, :update, :destroy]

  def index
    @posts = Post.published
                 .includes(:user, :category)
                 .recent
                 .page(params[:page])
                 .per(20)
  end

  def show; end

  def new
    @post = current_user.posts.build
  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 edit; 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_url, notice: "Post deleted.", status: :see_other
  end

  private

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

  def authorize_post!
    redirect_to posts_url, alert: "Not authorized." unless @post.user == current_user
  end

  def post_params
    params.require(:post).permit(:title, :body, :category_id, :status, :featured_image, tag_ids: [])
  end
end

Views and Partials

Use
```
_form.html.erb
```
partial shared between
```
new
```
and
```
edit
```
Use collection rendering:
```
render @posts
```
(auto-maps to
```
_post.html.erb
```
)

Use locals:

render partial: "post", locals: { post: @post }

Use
```
content_for :title
```
for page-specific titles
Use helpers for complex view logic (not inline ERB conditionals)

Routing

ruby

# config/routes.rb
Rails.application.routes.draw do
  root "home#index"

  # Authentication
  get "login", to: "sessions#new"
  post "login", to: "sessions#create"
  delete "logout", to: "sessions#destroy"

  # RESTful resources
  resources :posts do
    resources :comments, only: [:create, :destroy]
    member do
      post :publish
      post :unpublish
    end
  end

  resources :categories, only: [:index, :show] do
    resources :posts, only: [:index]
  end

  # Admin namespace
  namespace :admin do
    root "dashboard#index"
    resources :users
    resources :posts
  end

  # API namespace
  namespace :api do
    namespace :v1 do
      resources :posts, only: [:index, :show, :create, :update, :destroy]
    end
  end

  # Health check
  get "health", to: "health#show"
end

Route conventions:

Use
```
resources
```
for standard CRUD (generates 7 RESTful routes)
Use
```
only:
```
or
```
except:
```
to limit generated routes
Use
```
member
```
for actions on a specific record,
```
collection
```
for actions on the set
Nest resources only one level deep; use
```
shallow: true
```
for deeper nesting
Namespace admin and API routes separately

Migrations

ruby

# db/migrate/20240115000000_create_posts.rb
class CreatePosts < ActiveRecord::Migration[7.1]
  def change
    create_table :posts do |t|
      t.references :user, null: false, foreign_key: true
      t.references :category, foreign_key: true
      t.string :title, null: false
      t.text :body, null: false
      t.integer :status, default: 0, null: false
      t.datetime :published_at
      t.integer :comments_count, default: 0, null: false

      t.timestamps
    end

    add_index :posts, [:user_id, :status]
    add_index :posts, :published_at
  end
end

Use
```
t.references
```
for foreign keys (adds index automatically)
Use
```
t.timestamps
```
for
```
created_at
```
and
```
updated_at
```
Add composite indexes for common query patterns
Use
```
comments_count
```
with
```
counter_cache: true
```
on the association

Service Objects

ruby

# app/services/application_service.rb
class ApplicationService
  def self.call(...)
    new(...).call
  end
end

# app/services/posts/publish_service.rb
module Posts
  class PublishService < ApplicationService
    def initialize(post:, user:)
      @post = post
      @user = user
    end

    def call
      return ServiceResult.failure(["Not authorized"]) unless @user == @post.user

      ActiveRecord::Base.transaction do
        @post.update!(status: :published, published_at: Time.current)
        notify_subscribers
      end

      ServiceResult.success(@post)
    rescue ActiveRecord::RecordInvalid => e
      ServiceResult.failure(e.record.errors.full_messages)
    end

    private

    def notify_subscribers
      PostMailer.published(@post).deliver_later
    end
  end
end

Use
```
self.call(...)
```
class method pattern for clean invocation
Wrap multi-step operations in
```
ActiveRecord::Base.transaction
```
Return a result object (success/failure) instead of raising

Namespace services by domain:

Posts::PublishService

Users::CreateService

Rails Commands

bash

# Application
rails new myapp --database=postgresql --css=tailwind
rails new myapp --api                    # API-only mode
rails server                             # Start dev server
rails console                            # Interactive console
rails routes                             # List all routes

# Generators
rails generate model User name:string email:string
rails generate controller Posts index show new create
rails generate scaffold Article title:string body:text
rails generate migration AddStatusToPosts status:integer

# Database
rails db:create                          # Create database
rails db:migrate                         # Run pending migrations
rails db:rollback                        # Undo last migration
rails db:seed                            # Run seeds.rb
rails db:reset                           # Drop, create, migrate, seed

# Testing
rails test                               # Run all tests
rails test:models                        # Model tests only
rails test:system                        # System tests only

# Assets and dependencies
bundle install                           # Install gems
rails assets:precompile                  # Compile assets for production

Testing

Minitest (Default)

ruby

# test/models/post_test.rb
require "test_helper"

class PostTest < ActiveSupport::TestCase
  def setup
    @post = posts(:first_post)
  end

  test "valid post" do
    assert @post.valid?
  end

  test "invalid without title" do
    @post.title = nil
    assert_not @post.valid?
    assert_includes @post.errors[:title], "can't be blank"
  end

  test "publish! sets status and timestamp" do
    @post.publish!
    assert @post.published?
    assert_not_nil @post.published_at
  end
end

Testing Standards

Use fixtures (default) or
```
factory_bot
```
for test data
Test validations, associations, scopes, and instance methods on models
Test authentication, authorization, and response codes on controllers
Use system tests (Capybara) for critical user flows
Coverage target: >80% for models and services, >60% overall
Test names describe behavior:
```
test "user cannot edit others' posts"
```
See references/patterns.md for controller and system test examples

Dependencies

Core:

rails ~> 7.1

pg

puma

redis

turbo-rails

stimulus-rails

importmap-rails

Auth:

bcrypt

(has_secure_password)

Background:

sidekiq

Pagination:

kaminari

pagy

Dev/Test:

debug

capybara

selenium-webdriver

web-console

rack-mini-profiler

Optional:

rspec-rails

factory_bot_rails

faker

shoulda-matchers

webmock

Best Practices

Do

Follow RESTful conventions for routes and controllers
Use
```
includes
```
/
```
preload
```
on every association accessed in views
Extract business logic to service objects
Use scopes for all reusable query patterns
Use
```
find_each
```
for batch operations on large datasets
Use background jobs for email, notifications, and heavy processing
Use fragment caching for expensive view partials
Keep secrets in credentials or environment variables

Don't

Put business logic in controllers or views
Use
```
params.permit!
```
(mass-assignment vulnerability)
Use string interpolation in SQL queries
Skip database indexes on foreign keys
Use
```
Model.all
```
without pagination or limits
Modify migrations after they have been applied to production
Use
```
raw
```
/
```
html_safe
```
with user-provided data
Rely heavily on callbacks for business logic (use services)

Advanced Topics

For detailed code examples and advanced patterns, see:

references/patterns.md -- ActiveRecord advanced patterns, Hotwire/Turbo, Action Cable, ActiveJob, API mode, deployment, and testing strategies

rails

NPX Install

Tags

SKILL.md Content

Ruby on Rails Guide

Core Principles

When to Use Rails

Project Structure

Guardrails

Controllers

Models

Migrations

Security

Performance

MVC Conventions

Models

Controllers

Views and Partials

Routing

Migrations

Service Objects

Rails Commands

Testing

Minitest (Default)

Testing Standards

Dependencies

Best Practices

Do

Don't

Advanced Topics

External References