rails

Rails Conventions

Coding conventions and best practices for Ruby on Rails projects. Project-specific conventions (CLAUDE.md, style guides) always take priority over this guidance.

Related skills:

• API error responses (RFC 9457 problem details with the problem gem): /sorah-guides:rails-problem
• Protobuf-native APIs (Connect RPC with connect_rpc_rails, protobufable, protovalidate): /sorah-guides:rails-protobuf
• Sorbet typing: /sorah-guides:sorbet

Data Model — ActiveRecord

• Migrations: Specify column types, defaults, null constraints, and index definitions explicitly
• Index correctness: Unique vs non-unique; composite index column order matching query patterns
• Validations: Decide which layer enforces what — model-level validations vs database constraints
• Associations: has_many, belongs_to, has_one — specify dependent behavior and foreign key constraints

Architecture & Design

• Concerns: Extract shared behaviors as ActiveRecord or ActionController concerns
• Where logic lives: Model callbacks vs service objects vs controller-level orchestration — prefer service objects for complex business logic
• Controller design: Keep actions thin; use before_action filters and strong parameters (or a declared protobuf message, see /sorah-guides:rails-protobuf)
• Errors: Raise error classes that render as problem details; no per-class rescue_from (see /sorah-guides:rails-problem)

Configuration

• Namespaced settings: Use Rails.configuration.x.namespace.key with second-level namespacing; avoid single-level Rails.configuration.x.foo
• Centralize ENV access: Define configuration in config/environments/*.rb using ENV.fetch; avoid direct ENV access in application code
• Avoid Rails.env checks: Do not use Rails.env.production? or similar in application code; express environment differences through configuration values instead

# Good — config/environments/production.rb
Rails.configuration.x.oauth.client_id = ENV.fetch("OAUTH_CLIENT_ID")
Rails.configuration.x.session.idle_timeout = 30.minutes

# Good — application code
client_id = Rails.configuration.x.oauth.client_id

# Bad — direct ENV access in application code
client_id = ENV.fetch("OAUTH_CLIENT_ID")

# Bad — Rails.env check in application code
if Rails.env.production?