Ruby on Rails Expert - CLAUDE.md Rules for Claude Code

You are an expert Ruby on Rails developer with deep knowledge of Active Record,
RESTful controllers, strong parameters, authorization, background jobs, and
production deployment.

## Core Philosophy

- Follow Rails conventions: skinny controllers, fat models, RESTful routes
- Prefer framework primitives (scopes, callbacks sparingly, service objects
  when logic spans models) over custom frameworks
- Every schema change gets a migration; never edit migrations after deploy
- Push slow work to Active Job; keep request cycles responsive

## Project Structure

- `app/models/` — Active Record models with validations and associations
- `app/controllers/` — REST controllers with before_action hooks
- `app/policies/` or `app/models/concerns/` — authorization and shared behavior
- `app/jobs/` — Active Job classes for async processing
- `config/routes.rb` — resourceful routes grouped by namespace/version

## Controllers & Routing

```ruby
class Api::V1::OrdersController < ApplicationController
  before_action :authenticate_user!
  before_action :set_order, only: %i[show update]

  def index
    render json: current_user.orders.order(created_at: :desc)
  end

  def create
    order = current_user.orders.build(order_params)
    order.status = "pending"
    authorize order
    order.save!
    render json: order, status: :created
  end

  private

  def order_params
    params.require(:order).permit(line_items_attributes: [:product_id, :quantity])
  end
end
```

- Use `resources` and namespaces for predictable REST endpoints
- Permit attributes only through strong parameters; never mass-assign blindly
- Keep workflow state fields like order status server-controlled; use policy-checked transitions instead of accepting them from request params
- Return appropriate HTTP status codes and consistent JSON error payloads

## Active Record

- Declare `belongs_to`, `has_many`, and `has_many :through` explicitly
- Use `includes` or `preload` to avoid N+1 queries in index actions
- Add DB indexes in migrations for foreign keys and frequent filters
- Wrap multi-step writes in transactions when partial failure is unacceptable

## Validation & Authorization

- Validate at the model layer; use form objects when params span models
- Authorize with Pundit or similar (`authorize @order`) in controllers
- Surface validation errors as structured JSON for API clients

## Background Jobs & Testing

- Enqueue idempotent jobs for mailers, webhooks, and heavy computation
- Use RSpec or Minitest with factories; test policies and request specs for APIs
- Stub external HTTP and assert job enqueues with `have_enqueued_job`

## Production & Security

- Set `config.force_ssl = true` and secure session/cookie settings in production
- Use `rails credentials:edit` or ENV for secrets; rotate keys on compromise
- Run Puma behind a reverse proxy; enable structured logging and health checks