nityeshaga/claude-code-essentials/beautiful-rails-like-dhh

Beautiful Rails, Like DHH — Writing Rails the 37signals Way

Write Rails the way the best Rails developers alive write it — mined from two shipped 37signals products (Campfire, real-time chat; Fizzy, live multiplayer Kanban) plus their written style law. The payoff: whole production features in a handful of files, frontends that do everything an SPA does without a second codebase, and entire bug-classes made unwriteable.

The two sentences that govern everything

1. The throughline: Rails stays small because each layer trusts a convention at its boundary.
2. The yardstick: Count the edge cases this line absorbs for free — that judges every line, yours and others'.

Both are stated, derived, and worked in references/01-doctrine.md §1. Read it before any nontrivial work.

The ten rules (index — 01-doctrine.md carries the why; each maps to a P-number)

1. The model owns the consequence (P1) — facts → model _commit callbacks; call-path effects → explicit methods. Reaching for skip_x? You put a call-path fact on the record.
2. `_commit` means after-durable (P1+P9) — anything reaching outside the DB fires after_*_commit, never plain after_create/after_save (the ghost row).
3. Derive, don't store (P2) — any recomputable fact must not be stored; a stored copy is a second source of truth.
4. Security is the shape of your data access (P3) — load every record through Current.user; auth defaults closed, opened opt-out-by-name.
5. Find the noun (P6) — every custom controller verb is CRUD on a hidden noun. A model may have verbs; a controller may not.
6. One renderer; the wire carries HTML, not data (P5) — one partial paints every path, addressed by dom_id. No JSON contract, no client templates.
7. Polymorphism over conditionals (P7) — every if kind == "x" is a class you haven't named.
8. Give behavior a home (P8) — traits live in concerns; the include line IS the spec.
9. Put work at its right altitude (P9) — cheap-and-durable runs in-band; slow/flaky/fan-out crosses into a thin job thunk.
10. JS is thin, generic, server-configured (P4+P5) — domain-agnostic Stimulus, data-* as config, the URL carries the contract, the DOM attribute IS the state.

Routing: which reference to read, when

Read only what the task needs. Each file opens with its own "read this when" line and TOC.

The feature build loop

For any new feature, work in this order, asking the question at each step:

1. Model — What is the noun, and whose facts are its consequences? (02)
2. Routes — What noun is each verb hiding? resources/resource only. (03)
3. Controller — Can this be two lines? Load through Current.user, call one model verb. If longer, the model is missing a verb. (03, 10)
4. View — One partial, addressed by `dom_id`, serving every future path. (04)
5. Live layer — Pull or push? Regions → frames; surgical → streams; multi-user → broadcasts_refreshes + morph. (05, 06)
6. Polish — What's slow, what must the browser keep? Jobs (08), caching (09), thin Stimulus (07).

Run the yardstick on each layer as you write it: every guard, loop, and hand-typed string is a candidate for a convention that absorbs it.

Review mode

Reviewing a diff/PR/codebase: start with references/13-review-checklist.md (red-flag tables by layer, severity-ranked). Highest-signal first scan: unscoped Model.find(params[:id]) near a permission check; plain after_create/after_save touching the outside world; the same markup or id string in two places.

Anti-pattern quick table (teaser — left column = the agent default; 13 owns the detail)

Calibration

• Comprehensiveness ≠ ceremony. The doctrine produces less code. If it ever feels like ceremony, you've misread a pattern — recheck the owning reference.
• Respect existing conventions. Default for greenfield, lens for review — not a conversion mandate. Work with Tailwind/RSpec/Devise/Sidekiq/service objects; recommend the 37signals alternative when asked or when it clearly pays, never as a drive-by rewrite.
• The exceptions are part of the doctrine. Store a position for genuine user-intent order; plain after_save for work that must roll back; SPA for canvas-class apps (00 §6). Each reference marks its own exceptions; apply them knowingly and say why.
• Provenance tags "(Campfire)"/"(Fizzy)" = lifted from shipped production; both cited = house doctrine. "(Hotwire docs)" = distilled from the official Turbo/Stimulus handbooks.