Jr Rails Classic

Rails Classic Coding Style

Write Rails application code following 37signals conventions. Rich domain models, CRUD controllers, database-backed everything, Minitest with fixtures.

Core Workflow

1. Use generators first — rails g model, rails g controller, rails g migration. Generators produce correct file structure, test stubs, and route entries in one shot.
2. Implementation order — models → controllers → views → tests.
3. Ship, Validate, Refine — prototype to production, learn from real usage.
4. Let it crash — use bang methods, let Rails handle RecordInvalid with 422s.

Guardrails

• No service objects — use domain models namespaced under app/models/
• No custom controller actions — create new resources instead (REST mapping)
• No RSpec, no factory_bot — Minitest with fixtures only
• No Redis — Solid Queue, Solid Cache, Solid Cable
• No strftime in views — custom DATE_FORMATS in initializers
• Callbacks only for derived data and async dispatch — never business logic
• Database constraints over model validations for hard guarantees
• Pass IDs to jobs, not objects

Conventions Quick Reference

Naming

• Verbs for state changes: card.close, board.publish
• Predicates from record presence: card.closed?, card.golden?
• Concerns as adjectives: Closeable, Publishable, Watchable
• Controllers as nouns: Cards::ClosuresController
• Scopes as business terms: scope :active, scope :chronologically

REST Mapping

No custom actions. Create sub-resources:

Models — State as Records

Instead of booleans, create state records (timestamps + authorship for free):

class Card::Closure < ApplicationRecord
  belongs_to :card
  belongs_to :creator, class_name: "User"
end

module Closeable
  extend ActiveSupport::Concern

  included do
    has_one :closure, dependent: :destroy
  end

  def closed? = closure.present?
  def close(creator: Current.user) = create_closure!(creator: creator)
  def reopen = closure&.destroy
end

# Querying
Card.joins(:closure)          # closed
Card.where.missing(:closure)  # open

Concerns — Horizontal Behavior

Self-contained (associations + scopes + methods). 50–150 lines. Named for capabilities, not organization.

class Card < ApplicationRecord
  include Assignable, Closeable, Golden, Watchable, Searchable
end

POROs Under Model Namespace

Business logic that doesn't fit a concern:

# app/models/event/description.rb
class Event::Description
  def initialize(event) = @event = event
  def to_s = # ...
end

Validations

Minimal on model (data integrity), contextual on form objects (UI flows):

# Model — minimal
class User < ApplicationRecord
  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
  normalizes :email, with: ->(e) { e.strip.downcase }
end

# Migration — hard constraints
add_index :users, :email, unique: true
add_foreign_key :cards, :boards

Association Design

Always set :dependent on has_many/has_one. Use :inverse_of when Rails can't infer it.

Rails 7.1+ Patterns

# Delegated types
class Message < ApplicationRecord
  delegated_type :messageable, types: %w[Comment Reply Announcement]
end

# store_accessor for JSON/JSONB
class User < ApplicationRecord
  store_accessor :settings, :theme, :notifications_enabled
end

Database

# UUIDs (UUIDv7 — time-sortable)
create_table :cards, id: :uuid do |t|
  t.references :board, type: :uuid, foreign_key: true
end

# Counter caches
class Comment < ApplicationRecord
  belongs_to :card, counter_cache: true
end

# Default values with Current
class Card < ApplicationRecord
  belongs_to :creator, class_name: "User", default: -> { Current.user }
end

Controllers

Thin. Use concerns for shared behavior:

module CardScoped
  extend ActiveSupport::Concern
  included { before_action :set_card }

  private
    def set_card
      @card  = Card.find(params[:card_id])
      @board = @card.board
    end
    def render_card_replacement
      render turbo_stream: turbo_stream.replace(@card)
    end
end

class Cards::ClosuresController < ApplicationController
  include CardScoped
  def create  = @card.close   && render_card_replacement
  def destroy = @card.reopen  && render_card_replacement
end

Current Attributes

class Current < ActiveSupport::CurrentAttributes
  attribute :session, :user, :account, :request_id
  delegate :user, to: :session, allow_nil: true
end

Background Jobs

Thin wrappers — logic lives on the model:

module Watchable
  def notify_watchers_later = NotifyWatchersJob.perform_later(self)
  def notify_watchers
    watchers.each { |w| WatcherMailer.notification(w, self).deliver_later }
  end
end

class NotifyWatchersJob < ApplicationJob
  def perform(card) = card.notify_watchers
end

View Helpers

Date formatting via initializer (never strftime in views):

# config/initializers/date_formats.rb
Date::DATE_FORMATS[:default]    = "%d.%m.%Y"
Time::DATE_FORMATS[:default]    = "%d.%m.%Y %H:%M"
Time::DATE_FORMATS[:time_only]  = "%H:%M"

Use active_link_to gem for navigation active states.

Testing

• Minitest with fixtures, integration tests for controllers
• Test observable behavior, not implementation
• Don't mock what you can test for real
• VCR for external APIs

Preferred Stack

Gem Selection

1. Can vanilla Rails do this?
2. Is it the app's core concern? If yes, own the code
3. Does it add infrastructure? Database-backed alternatives exist
4. Is the complexity worth it?
5. Is it from someone you trust?

Deep Reference Files

Read these on demand when the task requires deeper guidance:

• Design patterns (form objects, query objects, strategies, etc.): reference/patterns.md
• Anti-patterns and code smells: reference/anti-patterns.md, reference/smells.md
• Refactoring recipes: reference/refactorings/ (002–010)
• Testing guide: reference/shared/testing.md
• Hotwire (Turbo + Stimulus): reference/shared/hotwire.md
• Background jobs + Continuations: reference/shared/jobs.md
• State machines (AASM): reference/shared/state_machines.md
• Callbacks scoring + extraction: reference/shared/callbacks.md
• Authorization (Pundit): reference/shared/authorization.md
• Notifications (Noticed): reference/shared/notifications.md
• Instrumentation / EventReporter: reference/shared/instrumentation.md
• Components (Phlex): reference/shared/components.md
• Serializers (API JSON): reference/shared/serializers.md
• Architecture layers: reference/shared/architecture.md
• Gem recommendations: reference/toolbelt.md

For frontend patterns (Stimulus controllers, Turbo Frames/Streams), invoke the relevant hwc-* skill alongside this one.