igmarin/rails-code-conventions

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

| Topic | Rule | |-------|------| | Style/format | Project linter(s) — detect and run as above; do not invent style rules here | | Principles | DRY, YAGNI, PORO where it helps, CoC, KISS | | Comments / tags | Explain why; tagged notes need actionable context | | Logging | First arg: static string; second arg: hash with event: key; no interpolation; backtrace on errors | | Deep stacks | Chain rails-stack-conventions → domain skills (services, jobs, RSpec) |

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.

| Trigger | Required tag | |---------|-------------| | Business-rule constant (rates, caps, thresholds) | NOTE: with the rule's source/owner | | Deferred work / known shortcut | TODO: with ticket or next step | | Workaround for a bug or external limitation | HACK: or FIXME: with the upstream issue | | Performance tradeoff or hot path | OPTIMIZE: with the measured concern |

# 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.

| Area | Path pattern | Guidance | |------|--------------|----------| | ActiveRecord performance | app/models/**/*.rb | Eager load in loops; prefer pluck / exists? / find_each. N+1: run bullet → fix eager loads → re-run clean | | Background jobs | app/workers/**/*.rb, app/jobs/**/*.rb | Depth: rails-background-jobs | | Error handling | app/services/**/*.rb, app/lib/**/*.rb, app/exceptions/**/*.rb | Domain exceptions + layer rescue_from; specs must cover rescue paths | | Logging / tracing | app/services/**/*.rb, app/workers/**/*.rb, app/jobs/**/*.rb, app/controllers/**/*.rb, app/repositories/**/*.rb | Structured logs (see above); APM spans/tags on hot paths when stack has APM | | Controllers | app/controllers/**/*_controller.rb | Strong params; thin actions → services; IDOR / PII → rails-security-review | | Repositories | app/repositories/**/*.rb | New repos only for SQL, caching, clear boundary, or external I/O — document why | | RSpec | spec/**/*_spec.rb | FactoryBot; request over controller specs; env: (or project pattern) for ENV; let > let! unless eager setup required; avoid heavy before when let is clearer | | Serializers | app/serializers/**/*.rb | Explicit keys; no N+1; preload associations passed in | | Service objects | app/services/**/*.rb | Single responsibility; .call / injected deps per ruby-service-objects; after extract, specs + caller still green | | SQL security | Raw SQL anywhere | Bind params / sanitize_sql_array; whitelist dynamic ORDER BY; document why raw SQL |

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

| Skill | When to chain | |-------|---------------| | rails-stack-conventions | Stack-specific: PostgreSQL, Hotwire, Tailwind | | ddd-rails-modeling | When domain concepts and invariants need clearer Rails-first modeling choices | | ruby-service-objects | Implementing or refining service objects | | rails-background-jobs | Workers, queues, retries, idempotency | | rspec-best-practices | Spec style, tests gate (red/green/refactor), request vs controller specs | | rails-security-review | Controllers, params, IDOR, PII | | rails-code-review | Full PR pass before merge |

Assets

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