/rails-dev

name: rails-dev
description: "Opinionated Rails conventions: rich models, concerns, CRUD-everything, state-as-records, minimal dependencies, Minitest with fixtures. Load this skill BEFORE any code-level thinking, not only before editing a file. It is required the moment a task touches Rails code in ANY way: designing or even just discussing a data model, schema, migration, entity, association, field, validation, class, or method name; writing, planning, reviewing, analyzing, testing, debugging, or refactoring; or proposing any model, table, column, route, or code snippet inline in chat. If you are about to name a model or sketch a column you are already in scope, even in an exploratory back-and-forth where no file is written yet. Do not let a \"we're just discussing\" framing defer it. Do NOT use for non-Rails backends, NestJS, or general architecture (use nestjs-modular-monolith or coding-guidelines)."
metadata:
  author: William Calderipe - github.com/wcalderipe
  version: '1.0.0'

Rails Conventions

Core Philosophy

• **Rich models** - Business logic lives in models, not service objects
• **Everything is CRUD** - New resource over new action (`resource :closure` not `post :close`)
• **State as records** - `Closure` model instead of `closed: boolean`
• **Concerns for composition** - `Closeable`, `Watchable`, `Commentable`
• **Explicit over clever** - Inline until repetition is real; an abstraction earns its place, it isn't built on speculation
• **Small interfaces** - No public method without a caller
• **Let it crash** - Bang methods (`create!`), handle failures at the boundary, not by pre-guarding (`references/error-handling.md`)
• **Invariants in the schema** - Hard rules (presence, uniqueness, ranges) are NOT NULL / unique / check constraints; validations are for user-facing messages, not the source of truth. References stay soft: no foreign keys, integrity at the model layer
• **Minimal dependencies** - Build it yourself before reaching for gems. No Devise, Pundit, RSpec, FactoryBot, ViewComponent, service/form objects, or decorators
• **Database-backed** - Solid Queue/Cache/Cable, no Redis
• **Test coverage** - Maintain roughly 1:1 test ratio (1 line test per line of code)

Reference Selection

This table is an index, not the content. The conventions live in the reference files, not in this table, the codebase, or general Rails knowledge. Match the task to the rows below and **read those files end to end before you design, write, review, or analyze the code**. Reading the row is not reading the reference; guessing from the codebase is how the wrong convention gets shipped.

| Task | Reference | |------|-----------| | Models, validations, associations, business logic | `references/model.md` | | Custom validators, validation rules reused across models | `references/validator.md` | | Error handling, rescue boundaries, reporting, retries | `references/error-handling.md` | | Controllers, CRUD actions | `references/crud.md` | | Routes, `config/routes.rb`, resource mapping | `references/routes.md` | | Concerns, shared behavior | `references/concerns.md` | | State tracking (not booleans) | `references/state-records.md` | | Authentication, authorization, sessions, IDOR scoping | `references/auth.md` | | Database migrations | `references/migration.md` | | Minitest, fixtures, testing | `references/test.md` | | Views, ERB, partials, helpers, presentation logic | `references/view.md` | | Turbo Frames, Turbo Streams, real-time | `references/turbo.md` | | Stimulus controllers, JS sprinkles | `references/stimulus.md` | | Background jobs, Solid Queue | `references/jobs.md` | | Concurrency, fibers, Async, external I/O | `references/async.md` | | Mailers, email notifications | `references/mailer.md` | | Fragment caching, HTTP caching | `references/caching.md` | | REST API, JSON responses | `references/api.md` | | Multi-tenancy, account scoping | `references/multi-tenant.md` | | Event tracking, activity logs | `references/events.md` | | Webhooks (inbound/outbound), inbox, idempotency | `references/webhooks.md` | | Code review, consistency check | `references/review.md` | | HTTP clients, external APIs, Faraday | `references/http-client.md` | | Logging, log messages, Rails.logger | `references/logging.md` |

Coding style

These are cross-cutting rules: they apply to every file, regardless of area. They do **not** replace the references. For anything area-specific (models, controllers, jobs, views, tests, …) you MUST ALWAYS load the matching reference from the table above before writing or reviewing the code.

Conditionals

Use an expanded `if/else` over a value-returning guard clause. A guard clause at the top of a method is fine when the body is non-trivial.

# Don't: value-returning guard clause for a simple branch
def status_label
  return "closed" if closed?
  "open"
end

# Do: expanded if/else
def status_label
  if closed?
    "closed"
  else
    "open"
  end
end

Method order

Class methods, then public (with `initialize` first), then private. Order methods vertically by invocation: a caller sits above its callees.

# Don't: callee above its caller, public after private
class Signup
  def create_member = Member.create!(email:)
  def call = create_member
end

# Do: class method, then the caller, then its callees
class Signup
  def self.call(...) = new(...).call

  def call = create_member

  private
    def create_member = Member.create!(email:)
end

Visibility

No blank line after `private`; indent the methods beneath it. A module of only private methods marks `private` at the top with a blank line after, not indented.

# Don't: blank line after private, methods not indented
class Card
  private

  def closure_exists? = closure.present?
end

# Do: no blank line, indented under private
class Card
  private
    def closure_exists? = closure.present?
end

Bang methods

Use `!` only when a non-bang counterpart exists (like `save`