Rails Code Conventions

Purpose: Your daily checklist for writing clean Rails code — design principles, per-path rules, logging, and comment discipline. When you are writing or reviewing any Rails code and need to know "how should this be structured?", this skill applies.

Use this skill when writing or reviewing Rails application code where design principles and per-area rules matter more than stack-specific UI choices (see rails-stack-conventions for Hotwire + Tailwind specifics).

Style source of truth: Style and formatting follow whatever linter(s) the project configures (see Linter — initial analysis below). This skill adds non-style behavior and architecture guidance only.

Linter — initial analysis

Before recommending style fixes or contradicting formatting rules:

1. Detect which linter(s) the repo uses — e.g. RuboCop (.rubocop.yml, rubocop in Gemfile), Standard Ruby (standardrb, standard gem), frontend linters (eslint.config.*, .eslintrc*, biome.json, etc.), or scripts in package.json / bin/ (lint, rubocop, standardrb).
2. Run the command the project documents or that matches the config (e.g. bundle exec rubocop, bundle exec standardrb, npm run lint). Do not assume RuboCop if the project uses Standard or another stack.

Quick Reference

Design Principles

Comments

• Comment the why, not the what (the code shows what).
• Use tags with enough context that a future reader can act: TODO:, FIXME:, HACK:, NOTE:, OPTIMIZE:.

# BAD — restates the method name, adds zero value
# Finds the user by email
def find_by_email(email)
  User.find_by(email: email)
end

# GOOD — explains intent and tradeoff
# Uses find_by (not find_by!) so callers can handle nil explicitly;
# downstream auth layer is responsible for raising on missing user.
def find_by_email(email)
  User.find_by(email: email)
end

Structured Logging

• First argument: static string (message key or human-readable template without interpolated values).
• Second argument: hash with structured fields (user_id:, order_id:, etc.).
• Do not build the primary message with string interpolation; put dynamic data in the hash.
• Include event: (or equivalent) for error or ops dashboards when the team uses tagged events.

# BAD — interpolation loses structure; cannot filter by user_id in log aggregators
Rails.logger.info("Processing order #{order.id} for user #{user.id}")

# GOOD — static message, structured data, filterable fields
Rails.logger.info("order.processing_started", {
  event: "order.processing_started",
  order_id: order.id,
  user_id: user.id,
  amount_cents: order.total_cents
})

Apply by area (path patterns)

Rules below apply when those paths exist in the project. If a path is absent, skip that row.

RSpec and let_it_be (test-prof)

• Only use let_it_be if the project already depends on the test-prof gem (check Gemfile / Gemfile.lock). Search before recommending it.
• If test-prof is not present, follow rspec-best-practices with let as the default; use let! only when lazy evaluation would break the example (e.g. callbacks, DB constraints that must exist before the action). Explicit setup is fine when clearer. Do not require adding test-prof / let_it_be unless the user asks to introduce it.

HARD-GATE: Tests Gate Implementation

When this skill guides new behavior, the tests gate still applies:

PRD → TASKS → TEST (write, run, fail) → IMPLEMENTATION → …

No implementation code before a failing test. See rspec-best-practices and rails-agent-skills.

Common Mistakes

Integration