37signals Rails Best Practices

Comprehensive coding principles and conventions for Ruby on Rails applications, as practiced at 37signals (Basecamp, HEY, Fizzy). Contains 56 rules across 8 categories, prioritized by architectural impact. Derived from official 37signals sources: the Fizzy codebase, STYLE.md, AGENTS.md, the Rails Doctrine, DHH’s “On Writing Software Well” series, and the unofficial 37signals style guide (265 Fizzy PRs).

When to Apply

Reference these guidelines when:

• Writing new Rails controllers, models, or views
• Deciding between gems and vanilla Rails
• Modeling state and database schema
• Setting up background jobs, caching, or real-time features
• Reviewing code for 37signals-style conventions
• Refactoring toward rich domain models
• Choosing authentication or authorization approach
• Adding Stimulus controllers or Turbo patterns

Rule Categories by Priority

Quick Reference

1. Architecture Fundamentals (CRITICAL)

• arch-rich-models – Rich Domain Models Over Service Objects
• arch-vanilla-rails – Vanilla Rails is Plenty
• arch-avoid-patterns – Deliberately Avoided Patterns and Gems
• arch-earn-abstractions – Earn Abstractions Through Rule of Three
• arch-build-before-gems – Build It Yourself Before Reaching for Gems
• arch-ship-to-learn – Start Simple — Add Complexity Only After Validation
• arch-domain-facades – Domain Models as Facades Over Internal Complexity
• arch-single-business-layer – Single Layer for Business Logic
• arch-custom-auth – Custom Passwordless Auth Over Devise

2. Controllers & REST (CRITICAL)

• ctrl-crud-only – CRUD Controllers Over Custom Actions
• ctrl-model-as-resources – Model Non-CRUD Operations as Separate Resources
• ctrl-thin-controllers – Thin Controllers with Rich Domain Models
• ctrl-params-expect – Use params.expect() for Parameter Validation
• ctrl-controller-concerns – Controller Concerns for Cross-Cutting Behavior
• ctrl-nested-resources – Nested Resources with scope module

3. Domain Modeling (HIGH)

• model-concerns – Concerns for Horizontal Code Sharing
• model-normalizes – Use normalizes Macro for Data Cleaning
• model-store-accessor – Use store_accessor for JSON Column Access
• model-delegated-type – Use delegated_type for Polymorphism
• model-counter-caches – Counter Caches to Prevent N+1 Count Queries
• model-touch-chains – Touch Chains for Cache Invalidation
• model-callbacks-auxiliary – Callbacks for Auxiliary Complexity
• model-event-tracking – Polymorphic Event Model for Activity Tracking
• model-poro-namespacing – Namespace POROs Under Parent Models

4. State Management (HIGH)

• state-records-over-booleans – Records as State Over Boolean Columns
• state-timestamps – Timestamps for State Transitions
• state-enums – Enums for Categorical States
• state-db-constraints – Database Constraints Over ActiveRecord Validations
• state-write-time – Compute at Write Time Not Read Time

5. Database & Infrastructure (HIGH)

• db-backed-everything – Database-Backed Everything
• db-solid-queue – Solid Queue for Background Jobs
• db-solid-cable – Solid Cable for Real-Time Pub/Sub
• db-solid-cache – Solid Cache for Application Caching
• db-multi-tenancy – Path-Based Multi-Tenancy with Current.account
• db-uuid-primary-keys – UUIDs as Primary Keys
• db-no-foreign-keys – No Foreign Key Constraints

6. Views & Frontend (MEDIUM)

• view-turbo-frames – Turbo Frames for Scoped Page Fragments
• view-turbo-streams – Turbo Streams for Real-Time Updates
• view-stimulus-targets – Stimulus Targets Over CSS Selectors
• view-stimulus-design – Stimulus Controller Design Principles
• view-helpers-not-partials – Extract Logic to Helpers Not Partials
• view-progressive-enhancement – Progressive Enhancement as Primary Pattern
• view-fragment-caching – Fragment Caching for View Performance
• view-http-caching – HTTP Caching with fresh_when and ETags

7. Code Style (MEDIUM)

• style-conditionals – Expanded Conditionals Over Guard Clauses
• style-method-ordering – Methods Ordered by Call Sequence
• style-positive-names – Use Positive Names for Methods and Scopes
• style-naming-return-values – Method Names Reflect Return Values
• style-visibility-modifiers – Visibility Modifier Formatting
• style-bang-methods – Bang Methods Only When Non-Bang Exists
• style-async-naming – Use _later and _now Suffixes for Async Operations

8. Testing (MEDIUM)

• test-minitest – Minitest Over RSpec
• test-fixtures – Database Fixtures Over FactoryBot
• test-no-damage – No Test-Induced Design Damage
• test-no-system-tests – Integration Tests Over System Tests
• test-behavior – Test Behavior Not Implementation

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files