| name | rails |
| description | Rails 7+ framework guardrails, patterns, and best practices for AI-assisted development.
Use when working with Rails projects, or when the user mentions Ruby on Rails.
Provides ActiveRecord, Hotwire/Turbo, Action Cable, and convention-over-configuration guidelines.
|
| license | MIT |
| metadata | {"author":"samuel","version":"1.0","category":"framework","language":"ruby","extensions":".rb,.erb"} |
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
class Post < ApplicationRecord
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
validates :title, presence: true, length: { maximum: 255 }
validates :body, presence: true
enum :status, { draft: 0, published: 1, archived: 2 }
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)}%")
}
before_validation :normalize_title
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
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
Rails.application.routes.draw do
root "home#index"
get "login", to: "sessions#new"
post "login", to: "sessions#create"
delete "logout", to: "sessions#destroy"
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
namespace :admin do
root "dashboard#index"
resources :users
resources :posts
end
namespace :api do
namespace :v1 do
resources :posts, only: [:index, :show, :create, :update, :destroy]
end
end
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
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
class ApplicationService
def self.call(...)
new(...).call
end
end
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
rails new myapp --database=postgresql --css=tailwind
rails new myapp --api
rails server
rails console
rails routes
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
rails db:create
rails db:migrate
rails db:rollback
rails db:seed
rails db:reset
rails test
rails test:models
rails test:system
bundle install
rails assets:precompile
Testing
Minitest (Default)
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 or 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
External References