Ruby

Purpose

Write Ruby that stays readable as it grows: small objects with clear responsibilities, controllers that stay thin, and ActiveRecord queries that do not quietly issue a query per row.

When to Use

• Writing or reviewing Ruby and Rails code.
• Refactoring fat models or fat controllers.
• Diagnosing slow endpoints caused by ActiveRecord.
• Structuring an RSpec suite.
• Designing background jobs and their retry semantics.

Capabilities

• Object design: service objects, form objects, query objects, value objects.
• ActiveRecord: eager loading, scopes, batching, index-aware querying.
• Background processing with Sidekiq or Active Job, including idempotency.
• RSpec structure: request specs, model specs, factories, shared examples.
• RuboCop and Sorbet/RBS typing where valuable.

Inputs

• Application source, Gemfile, Rails version.
• Slow-query or profiling data when performance is the concern.

Outputs

• Controllers that authenticate, authorize, delegate, and render — nothing else.
• Named scopes and eager-loaded queries with no N+1.
• Specs that describe behavior rather than restate implementation.

Workflow

1. Locate the responsibility — If a method touches HTTP, business rules, and persistence, split it before changing it.
2. Extract a service object — One public call, explicit dependencies, no global state.
3. Fix the queries — Add includes, convert loops into set operations, batch with find_each.
4. Make jobs idempotent — Retries are guaranteed; double-execution must be harmless.
5. Gate — RSpec, RuboCop, and Bullet (or equivalent) to fail the build on N+1.

Best Practices

• Controllers do not contain business logic. If a controller action exceeds ten lines, extract.
• Callbacks (after_save, before_create) create action at a distance. Prefer explicit service calls.
• Use find_each for anything that could exceed a few thousand rows; all.each loads the table into memory.
• Every background job should be safe to run twice. Key the side effect, not the invocation.
• rescue => e without re-raising swallows bugs. Rescue the specific class.
• Freeze constants and prefer immutable value objects for domain concepts.

Examples

Service object with explicit failure:

# frozen_string_literal: true

class RefundOrder
  Result = Struct.new(:success?, :refund, :error, keyword_init: true)

  def initialize(gateway: PaymentGateway.new)
    @gateway = gateway
  end

  def call(order:, amount_cents:)
    return failure("order not refundable") unless order.refundable?
    return failure("amount exceeds order total") if amount_cents > order.total_cents

    refund = @gateway.refund(order.charge_id, amount_cents)
    order.update!(refunded_cents: order.refunded_cents + amount_cents)
    Result.new(success?: true, refund: refund)
  rescue PaymentGateway::Error => e
    failure(e.message)
  end

  private

  def failure(message) = Result.new(success?: false, error: message)
end

Notes

• Bullet in the test environment, configured to raise, turns N+1 queries into failing tests.
• frozen_string_literal: true is worth adding to every file; string allocation is a real cost in hot paths.
• Sidekiq retries with exponential backoff by default. Set sidekiq_options retry: explicitly rather than relying on the default for anything that touches money.