Skip to content
37signals-rails-style logo

37signals/DHH Rails Style Guide

37signals-rails-style

Apply 37signals/DHH Rails conventions when writing Ruby on Rails code. Use when building Rails applications, reviewing Rails code, or making architectural decisions. Covers various aspects of Rails application architecture, design and dependencies.

SKILL.md

Full skill instructions

37signals/​DHH Rails Style Guide

Core Philosophy

  • "Vanilla Rails is plenty." Maximize what Rails gives you, minimize dependencies, resist abstractions until necessary.
  • Rich domain models over service objects
  • CRUD controllers over custom actions
  • Concerns for horizontal code sharing
  • Records as state over boolean columns
  • Database-backed everything (no Redis)
  • Build it yourself before reaching for gems

Dependencies

Use

  • Rails (edge), turbo-rails, stimulus-rails, importmap-rails, propshaft, solid_queue, solid_cache, solid_cable (database-backed, NO Redis), geared_pagination, bcrypt, rqrcode, redcarpet

Avoid

Gem/​PatternWhy
deviseAuth is ~150 lines of custom code
pundit/cancancanAuthorization lives in models
dry-rb, interactorOver-engineered
view_componentERB partials are fine
sidekiq, redisUse Solid Queue (database-backed)
graphqlREST with Turbo is sufficient

Routing: Everything is CRUD

Every action maps to a CRUD verb. Create new resources instead of custom actions:

# Avoid: Custom actions
resources :cards do
  post :close
end

# Good: State changes as resources
resources :cards do
  resource :closure      # POST to close, DELETE to reopen
  resource :pin          # POST to pin, DELETE to unpin
  resource :watch        # POST to watch, DELETE to unwatch
end

Use scope module: for namespaced nested resources. Use resolve for custom polymorphic URL generation.


Controllers

Thin Controllers, Rich Models

Controllers orchestrate; business logic lives in models.

def create
  @card.close  # All logic in model
  respond_to do |format|
    format.turbo_stream { render_card_replacement }
    format.json { head :no_content }
  end
end

Controller Concerns

Use concerns for shared behavior:

  • Resource scoping: CardScoped, BoardScoped - load parent resources via before_action
  • Request context: CurrentRequest - populate Current with request data
  • Security: BlockSearchEngineIndexing, RequestForgeryProtection
  • Turbo helpers: TurboFlash - flash messages via Turbo Stream

Authorization

Check permissions in controller, define permission logic in model:

# Controller
before_action :ensure_permission_to_administer_card, only: [:destroy]

# Model
def can_administer_card?(card)
  admin? || card.creator == self
end

Models & Concerns

Heavy Use of Concerns

Each concern is self-contained with associations, scopes, and methods:

class Card < ApplicationRecord
  include Assignable, Closeable, Eventable, Pinnable, Watchable
end

Concern Structure

module Card::Closeable
  extend ActiveSupport::Concern

  included do
    has_one :closure, dependent: :destroy
    scope :closed, -> { joins(:closure) }
    scope :open, -> { where.missing(:closure) }
  end

  def closed? = closure.present?

  def close(user: Current.user)
    create_closure!(user: user) unless closed?
  end
end

Default Values via Lambdas

belongs_to :account, default: -> { board.account }
belongs_to :creator, class_name: "User", default: -> { Current.user }

Current for Request Context

Use ActiveSupport::CurrentAttributes for session, user, identity, account, and request metadata.

POROs (Plain Old Ruby Objects)

Namespace under parent model: Event::Description, Card::Eventable::SystemCommenter

Use for:

  • Presentation logic - formatting for display
  • Complex operations - multi-step processes
  • View context bundling - collecting UI state

POROs are model-adjacent, NOT controller-adjacent (that would be a service object).


State as Records, Not Booleans

Create separate records instead of boolean columns:

# Separate record gives you: timestamp, who did it, easy scoping
class Closure < ApplicationRecord
  belongs_to :card, touch: true
  belongs_to :user, optional: true
end

card.closure.present?     # Is it closed?
card.closure.user         # Who closed it?
card.closure.created_at   # When?

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

Examples: Closure, Pin, Watch, Publication, Goldness


Authentication

Custom passwordless magic link auth (~150 lines). No Devise.

Key components:

  • Authentication concern with require_authentication, resume_session, start_new_session_for
  • Session model (belongs_to identity)
  • MagicLink model with expiration and consumption
  • Bearer token authentication for API access

Views & Turbo/​Hotwire

  • Turbo Streams for partial updates (turbo_stream.replace, turbo_stream.before)
  • Morphing for complex updates (method: :morph)
  • Partials over ViewComponents - standard ERB partials with caching
  • Stimulus controllers - single-purpose, small (~50 lines), static values/static classes for config, this.dispatch() for events, this.#privateMethod() for private methods

Background Jobs

  • Shallow jobs, rich models - jobs just call model methods
  • _later and _now convention - mark_as_read_later queues job, mark_as_read_now executes immediately
  • Solid Queue - database-backed, no Redis
  • Recurring jobs via config/​recurring.yml

Testing

  • Request specs for controllers (not controller specs)
  • Ship tests with features in the same commit
  • Use change { }, as: :turbo_stream, as: :json

What They Avoid

  • No service objects - use model methods
  • No form objects (usually) - exception: Signup as ActiveModel
  • No decorators/​presenters - use view helpers
  • No GraphQL - REST with Turbo

Naming Conventions

Methods

  • Verbs for actions: close, reopen, publish
  • Predicates for state: closed?, published?

Concerns

Adjectives describing capability: Closeable, Publishable, Watchable, Searchable

Controllers

Nouns matching the resource: Cards::ClosuresController, Boards::PublicationsController

Scopes

  • Ordering: chronologically, reverse_chronologically, alphabetically, latest
  • Preloading: preloaded as standard name for eager loading
  • Parameterized: indexed_by(index), sorted_by(sort)

Caching

HTTP Caching

  • fresh_when etag: [...] for conditional GET
  • Global etag { "v1" } in ApplicationController (bump to bust caches)
  • Concern-level ETags for timezone, authentication

Fragment Caching

  • cache card do in views
  • cached: true for collection rendering
  • touch: true on associations for cache invalidation

Database Patterns

  • UUIDs for primary keys
  • Every model has account_id for multi-tenancy
  • URL-based multi-tenancy: /​{account_id}/​boards/​...
  • No foreign key constraints - removed for flexibility

CSS Architecture

  • Vanilla CSS no Sass, PostCSS, or Tailwind.
  • CSS Cascade Layers @layer reset, base, components, modules, utilities
  • OKLCH color system with CSS variables
  • Modern features @starting-style, color-mix(), :has(), native nesting, container queries

API Design

  • Same controllers, different format via respond_to
  • Response codes: Create → 201 Created + Location, Update/​Delete → 204 No Content
  • Bearer token authentication

Callbacks

Use sparingly:

  • after_commit :relay_later, on: :create for async work
  • before_save :set_defaults for derived data
  • Avoid complex chains, avoid synchronous external calls

Summary

  1. Start with vanilla Rails - Don't add abstractions until you feel the pain
  2. Models are rich - Business logic lives in models, not services
  3. Controllers are thin - Just orchestration and response formatting
  4. Everything is CRUD - New resource over new action
  5. State is records - Not boolean columns
  6. Concerns are compositions - Horizontal behavior sharing
  7. Build before buying - Auth, search, jobs - all custom
  8. Database is king - No Redis, no Elasticsearch
  9. Test with fixtures - Deterministic, fast, simple
  10. Ship incrementally - Many small commits
  11. Tests ship with features - Not TDD, not afterthought, but together
  12. Refactor toward consistency - Establish patterns, then update old code
  13. CSS uses the platform - Native layers, nesting, OKLCH - no preprocessors
  14. Design tokens everywhere - CSS variables for colors, spacing, typography

The best code is the code you don't write. The second best is the code that's obviously correct.

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View