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

Code Review / Refactoring Workflow

When reviewing or refactoring Rails code, follow this sequence:

1. Run linter — detect config, run the appropriate tool, note absence if none found.
2. Check area-specific rules — apply the "Apply by area" table below to each changed path.
3. Verify tests gate — confirm failing tests exist before any new behavior; run specs and checkpoints.
4. Chain to specialised skills — use the Integration table to pull in deeper guidance (security, jobs, specs, etc.) as needed.

Comments and tagged notes

Comment why, not what. Tagged notes — TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE: — are MANDATORY in these triggers; every tag carries actionable context (owner, ticket id, deadline, or next step). Naked tags (# TODO: fix this) fail review.

# BAD — naked tag, no context
# TODO: fix this
rate = TIER_RATES.fetch(tier, 0.0)

# GOOD
# NOTE: 50% cap set by Pricing policy v3 (PRI-118, owner: pricing-team).
MAX_DISCOUNT = 0.50

# GOOD — TODO with next step + dependency
# TODO: replace TIER_RATES with DB-backed lookup (PRI-482; blocked on legal).
rate = TIER_RATES.fetch(tier, 0.0)

Structured Logging

MANDATORY SHAPE — every Rails.logger.* call uses exactly two positional arguments.

Rails.logger.<level>(static_string_message, { event: "dot.namespaced", ...domain_fields })
#                    └── 1st arg: STRING ──┘  └─────────── 2nd arg: HASH ───────────┘

• 1st arg (string): a static string literal — no interpolation, no variables. Log aggregators group on this dimension.
• 2nd arg (hash): first key is always event: with a dot-namespaced value (do NOT use :type, :action, or :name). All dynamic data goes here.
• Errors: every rescue logs both e.message and e.backtrace.first(5).join("\n") as hash fields — backtrace is non-optional.

# BAD — interpolation destroys log aggregator grouping; single-arg call loses structured fields
Rails.logger.info("Processing order #{order.id}")
Rails.logger.info(event: "order.processing_started", order_id: order.id)

# GOOD
Rails.logger.info("order.processing_started", {
  event: "order.processing_started",
  order_id: order.id,
  user_id: user.id
})

# GOOD — error path with backtrace
rescue StandardError => e
  Rails.logger.error("order.processing_failed", {
    event: "order.processing_failed",
    order_id: order.id,
    error: e.message,
    backtrace: e.backtrace.first(5).join("\n")
  })
  raise
end

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 recommend let_it_be if test-prof is already in Gemfile.lock. Otherwise default to let; reach for let! only when lazy evaluation would break the example. Don't introduce test-prof unless asked.

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.

Output Style

Every Rails-code task lands these:

1. Comments follow the Comments and tagged notes section: no what-comments; tagged notes (TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE:) on every assumption, deferred work, or business-rule constant; every tag carries actionable context (owner, ticket id, deadline).
2. Logging follows Structured Logging above — static first arg, hash second arg with event:, and a backtrace line on every error rescue.
3. Linter detection noted — when reviewing or refactoring, state which linter config you detected (or its absence) before any style claim.

Integration

Assets

• assets/checklist.md
• assets/snippets.md