CLAUDE.md for Ruby on Rails: 13 Rules That Stop AI from Fighting the Framework

## Stack
- Rails: 7.2.x (NOT 6.x or 8.x — routing, Hotwire, and async defaults differ)
- Ruby: 3.3
- Database: PostgreSQL 16
- Key gems: Devise 4.9, Sidekiq 7.x, RSpec 3.13, Hotwire (Turbo + Stimulus)
- Asset pipeline: Propshaft (NOT Sprockets)

## Architecture
Controllers do ONE thing: accept a request, call a service object, return a response.
Business logic goes in app/services/ as plain Ruby objects (POROs).
Never put database queries, calculations, or multi-step operations in controllers.

# CORRECT
class OrdersController < ApplicationController
  def create
    result = Orders::CreateService.call(order_params, current_user)
    if result.success?
      redirect_to result.order, notice: 'Order created'
    else
      render :new, status: :unprocessable_entity
    end
  end
end

# WRONG
def create
  @order = Order.new(order_params)
  @order.user = current_user
  @order.calculate_totals
  @order.apply_discount_if_eligible
  @order.save
  OrderMailer.confirmation(@order).deliver_later
  # ... 40 more lines
end

## Active Record Callbacks
Callbacks (before_save, after_create, etc.) are ONLY for data integrity concerns
that must always apply regardless of context (e.g., normalizing a field value).
NEVER use callbacks for:
- Sending emails or notifications
- Calling external APIs
- Triggering background jobs
- Business logic that depends on context

# WRONG — callback couples model to mailer
after_create :send_welcome_email
private
def send_welcome_email
  UserMailer.welcome(self).deliver_later
end

# CORRECT — call explicitly from service/controller
Orders::CreateService.call(params).tap do |result|
  OrderMailer.confirmation(result.order).deliver_later if result.success?
end

## Querying
All query logic goes in model scopes or query objects, not in controllers.
Use named scopes for reusable conditions.
Use query objects in app/queries/ for complex multi-table queries.
NEVER write where("column = ?") directly in controllers or views.

# CORRECT — model scope
class Order < ApplicationRecord
  scope :pending, -> { where(status: 'pending') }
  scope :for_user, ->(user) { where(user: user) }
  scope :recent, -> { order(created_at: :desc).limit(10) }
end

# In controller
@orders = Order.pending.for_user(current_user).recent

## Background Jobs
ANY operation that sends email, calls an external API, processes files, or takes
>200ms MUST be performed in a background job using Sidekiq (or your configured
adapter). Never process these synchronously in controllers.

# CORRECT
OrderFulfillmentJob.perform_later(order.id)
WelcomeEmailJob.perform_later(user.id)

# WRONG
OrderFulfillmentService.call(order)  # blocks the HTTP response
UserMailer.welcome(user).deliver_now # synchronous email

## Strong Parameters
ALL controller actions that accept user input MUST use explicit strong parameters.
Never pass params directly to model methods.
List every permitted attribute explicitly — no permit!

# CORRECT
def order_params
  params.require(:order).permit(:product_id, :quantity, :shipping_address_id)
end

# WRONG
Order.create(params[:order])        # mass-assignment vulnerability
Order.create(params.permit!)        # permits everything — never do this

## Hotwire / Turbo (Rails 7+)
This app uses Hotwire (Turbo + Stimulus). Do NOT generate React, Vue, or
jQuery-based UI patterns.
Controller actions that handle Turbo requests respond with:
- Turbo Stream responses for partial page updates
- Turbo Frame responses for in-frame navigation
- Standard redirects for full-page transitions

Format responses explicitly:
respond_to do |format|
  format.turbo_stream { render turbo_stream: turbo_stream.replace('orders', ...) }
  format.html { redirect_to orders_path }
end

## Concerns
Rails concerns (ActiveSupport::Concern) are ONLY for behavior that is genuinely
shared across multiple unrelated models or controllers.
Do NOT use concerns as a way to split up a large model — extract to a service object instead.

# CORRECT use case — Auditable concern shared by Order, Product, User
module Auditable
  extend ActiveSupport::Concern
  included do
    has_many :audit_logs, as: :auditable
  end
end

# WRONG — concern is just a fat model split across files
module OrderPricing  # Only used by Order — should be a service object
  extend ActiveSupport::Concern
  ...
end

## Authentication
This app uses Devise for authentication.
- current_user is available in all controllers and views
- Use before_action :authenticate_user! to protect actions
- NEVER implement custom session management or password handling
- User model: app/models/user.rb (Devise modules: :database_authenticatable, :registerable, :recoverable, :rememberable, :validatable)

# CORRECT
before_action :authenticate_user!

def create
  @order = current_user.orders.build(order_params)
end

# WRONG — custom auth
def authenticate
  session[:user_id] = User.find_by(email: params[:email])&.id
end

## Testing
This project uses RSpec (NOT Minitest/Test::Unit).
Test structure:
- spec/models/ — unit tests for model validations, scopes, methods
- spec/requests/ — integration tests for controller/routing
- spec/services/ — unit tests for service objects
- spec/jobs/ — unit tests for background jobs
Use FactoryBot for fixtures. Never use Rails fixtures (test/fixtures/).
Use Shoulda Matchers for model validation tests.

# CORRECT
RSpec.describe Order, type: :model do
  let(:order) { build(:order) }
  it { is_expected.to belong_to(:user) }
  it { is_expected.to validate_presence_of(:status) }
end

## Database Constraints
Every model validation that enforces data integrity MUST have a corresponding
database constraint in the migration.
Validations alone are insufficient — they can be bypassed.

# Model
validates :email, presence: true, uniqueness: true

# Migration — REQUIRED matching constraint
add_index :users, :email, unique: true
add_column :users, :email, :string, null: false

## Internationalization
ALL user-facing strings (flash messages, error messages, email subjects, UI labels)
MUST use Rails i18n helpers. Never hardcode English strings in controllers or views.

# CORRECT
flash[:notice] = t('orders.create.success')
# In config/locales/en.yml: orders.create.success: "Order created successfully"

# WRONG
flash[:notice] = "Order created successfully"

## Query Performance
ALWAYS use eager loading (includes, preload, eager_load) when accessing
associations in views or serializers.
Before adding any collection query, identify all associations accessed in the
view/serializer and include them in the query.

# CORRECT
@orders = Order.includes(:user, :items => :product).pending.recent

# WRONG — N+1 in the view
@orders = Order.pending.recent
# View: orders.each { |o| o.user.name }  # fires 1 query per order