# Rails Best Practices Core

> Apply core Ruby on Rails best practices for architecture, naming, safety, and maintainability. Use for most Rails coding, refactoring, and code review tasks so baseline standards stay consistent.

- Skill: `marckohlbrugge/rails-best-practices-core-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add marckohlbrugge/rails-best-practices-core-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marckohlbrugge/rails-best-practices-core-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: marckohlbrugge (https://skillmd.com/u/marckohlbrugge)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/marckohlbrugge/rails-best-practices-core-2

---


# Rails Best Practices Core

Use this as the default baseline for Rails work. Distilled from 37signals codebases (Campfire, Fizzy) and DHH's review patterns.

## Core Defaults

- Prefer clear, explicit code over clever abstractions. Abstractions must earn their keep; if you can't point to 3+ variations that need it, inline it.
- Keep controllers thin and put domain behavior in models.
- Prefer Rails conventions and built-ins before adding gems.
- Model state and behavior with domain concepts, not ad-hoc flags.
- Scope tenant/user data through ownership boundaries.
- Favor database constraints for hard invariants; only validate in AR when you need user-facing error messages.
- Keep interfaces small; don't add public methods that aren't used anywhere.
- Prefer write-time computation over expensive read-time composition (counter caches, delegated types, precomputed roll-ups, `dependent: :delete_all` when no callbacks needed).
- Use `params.expect(...)` for strong params in modern Rails.
- Let it crash: bang methods (`create!`), handle exceptions at boundaries. Only use `!` when a non-bang counterpart exists.
- Fix root causes, not symptoms (e.g. `enqueue_after_transaction_commit` over retry logic for races).
- Ship tests in the same PR as behavior changes.

## Modeling Patterns

- **State as records, not booleans.** Instead of `closed: boolean`, create a `Closure` record with `creator` and timestamps. You get who/when for free, and scoping is trivial:

```ruby
has_one :closure, dependent: :destroy
scope :closed, -> { joins(:closure) }
scope :open, -> { where.missing(:closure) }
```

- **Slice large models into concerns** named for capability (`Closeable`, `Watchable`, `Assignable`), each self-contained (associations + scopes + methods), ~50-150 lines, cohesive. Prefer nested modules under the model's namespace (`Card::Closeable` in `app/models/card/closeable.rb`) for domain slices; reserve `app/models/concerns/` for genuinely cross-model behavior. Never extract concerns containing only private methods.
- **POROs live in `app/models/`**, not `app/services/`: presentation objects (`Event::Description`), complex operations (`SystemCommenter`), view-context bundles (`User::Filtering`). They're model-adjacent, not controller-adjacent.
- **Default values via lambdas:** `belongs_to :creator, class_name: "User", default: -> { Current.user }`; `belongs_to :account, default: -> { board.account }`.
- **Current attributes for request context** (`Current.user`, `Current.account`), with cascading setters (assigning `session` resolves `identity`, which resolves `user` for the account).
- **Callbacks for setup/cleanup, not business logic.** Keep callback counts low.
- **Rails shortcuts to reach for:** `normalizes` (data cleanup before validation), `store_accessor` (JSON columns), `delegated_type` (heterogeneous collections), `generates_token_for` (expiring signed tokens), string enums via `enum :status, %w[drafted published].index_by(&:itself)`, `after_save_commit`, `touch: true` chains for cache invalidation, `delegate`.
- **Association extensions for bulk domain operations:** define `grant_to`/`revise` on the `has_many` proxy; use `insert_all` for bulk creates and `dependent: :delete_all` on join tables with no callbacks.
- **Human-friendly URLs:** override `to_param` with a per-tenant `number` rather than exposing raw IDs/UUIDs.

## Naming

- Spend time on names — naming is design. `Closure` beats `CardClose`; `Mention` beats `UserReference`.
- Positive names: `active` not `not_deleted`, `visible` not `not_hidden`.
- Semantic associations named for role: `belongs_to :creator, class_name: "User"` not `belongs_to :user`.
- Domain-driven over technical: `quota.depleted?` not `quota.over_limit?`.
- Business-focused scopes: `:active`, `:unassigned`, `:golden` — not SQL-ish `:without_pop`.
- Consistent domain language: don't mix `source`/`resource`/`container` for one concept.

## REST & Routing

- Everything is CRUD: turn verbs into nouns. Close → `resource :closure` (POST closes, DELETE reopens); publish → `resource :publication`. No custom member actions.
- Singular `resource` for one-per-parent state; `scope module:` to group nested controllers (`Cards::ClosuresController`); shallow nesting for deep hierarchies.
- Resource-scoping controller concerns (`CardScoped` sets `@card` via `Current.user.accessible_cards.find_by!(...)`) shared across nested controllers, including shared Turbo render helpers.
- `resolve "Comment"` for polymorphic URL generation to the parent with an anchor.
- Same controllers serve HTML/Turbo/JSON via `respond_to` — no separate API namespace.

## Authorization

- No Pundit/CanCanCan: simple predicate methods on models (`card.editable_by?(user)`, `user.can_administer_board?(board)`).
- Controllers check (`head :forbidden unless ...`), models define what the permission means.
- Declarative controller macros for auth posture: `allow_unauthenticated_access`, `ensure_can_administer`.

## Dependencies

Before adding a gem ask: can vanilla Rails do this? Is 50-150 lines in-repo simpler than a dependency? Commonly skipped: Devise, Pundit, ViewComponent, RSpec, FactoryBot, Redis (Solid Queue/Cache/Cable use the DB), service objects, form objects, decorators, GraphQL, SPA frameworks, Tailwind.

## Review Priorities

1. Correctness and data safety.
2. Multi-tenant/security boundaries.
3. Maintainability and readability.
4. Performance hot spots.
5. Style and polish.

## Always Flag

- Unscoped record lookups in tenant-aware flows (`Comment.find(params[:id])`).
- New dependencies without strong justification.
- In-memory filtering/sorting that belongs in SQL (and `.map(&:name)` where `.pluck(:name)` works).
- Service objects replacing straightforward model methods.
- Non-RESTful custom actions when resource modeling is clearer.
- Boolean state columns where a record would capture who/when.
- Pages with forms using HTTP caching (`fresh_when`/etag) — stale CSRF tokens cause 422s.
- String status checks (`status == "x"`) when predicate-style APIs are available (StringInquirer / string enums).
- `validates :x, uniqueness: true` without a backing unique index.
- Helpers depending on implicit instance variables instead of explicit arguments.
- Unescaped interpolation into `html_safe` strings — escape first: `"<b>#{h(input)}</b>".html_safe`.
- Metaprogramming for 2-3 cases — just write the methods.
- Private-only concerns — inline them.

## Review Output

- Start with highest-severity findings.
- For each finding: issue, impact, concrete fix with file:line references.
- Be direct and practical; "This is over-engineered" is a complete sentence.
- End with either `Ship it` or a short prioritized fix list.