Rails Code Conventions

Style source of truth: Style and formatting defer to the project's configured linter(s). This skill adds non-style behavior and architecture guidance only. For Hotwire + Tailwind specifics, see rails-stack-conventions.

Linter — initial analysis

Detect → run → defer. Do not invent style rules.

• Ruby: check for .rubocop.yml / standard gem → bundle exec rubocop or bundle exec standardrb
• Frontend: check for eslint.config.*, .eslintrc*, biome.json, or package.json lint script → run accordingly
• If no config is found: note this to the user — do not default to any tool.

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