/ruby-rules

name: ruby-rules
description: "Ruby coding rules: style, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop."
effort: medium
user-invocable: false
allowed-tools: Read

Ruby Rules

These rules come from `app/rules/ruby/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Ruby. Apply them when writing or reviewing Ruby code.

Ruby Coding Style

Naming

• PascalCase: classes, modules.
• snake_case: methods, variables, file names, directories.
• UPPER_SNAKE: constants (`MAX_RETRIES = 3`).
• Prefix boolean methods with predicate: `empty?`, `valid?`, `admin?`.
• Suffix dangerous methods with `!`: `save!`, `sort!`, `strip!`.
• Use `_` prefix for intentionally unused variables: `_unused`.

Methods

• Keep methods short: 5-10 lines ideal. Extract helper methods.
• Use keyword arguments for methods with >2 parameters.
• Use default parameter values instead of checking for nil.
• Use `def method_name = expression` (Ruby 3.0+) for one-liners.
• Prefer `each` over `for` loops. Use block-style iteration.
• Return values implicitly (last expression). Use explicit `return` only for early exit.

Blocks, Procs, Lambdas

• Use `{ }` for single-line blocks. Use `do...end` for multi-line blocks.
• Use `&:method` shorthand: `names.map(&:upcase)`.
• Use lambdas for strict argument checking. Use procs for flexible arity.
• Use `yield` for single-block methods. Use explicit `&block` for storing/forwarding.

Classes

• Use `attr_reader`, `attr_writer`, `attr_accessor` for simple getters/setters.
• Use `Struct` for simple data containers. Use `Data.define` (Ruby 3.2+) for immutable.
• Use modules for mixins: `include` for instance methods, `extend` for class methods.
• Use `frozen_string_literal: true` magic comment at the top of every file.
• Use `private` / `protected` keywords to control method visibility.

Collections

• Use `map`, `select`, `reject`, `reduce`, `flat_map` for transformations.
• Use `each_with_object` over `inject` when accumulating into a mutable object.
• Use `dig` for safe nested hash/array access: `data.dig(:user, :address, :city)`.
• Use `Hash#fetch` with default for explicit missing-key handling.
• Use `Enumerable#lazy` for large collection processing.

Pattern Matching (Ruby 3+)

• Use `case/in` for structural pattern matching on hashes and arrays.
• Use `=>` pin operator to match against existing variables.
• Use `in` pattern for conditional deconstruction in `if` statements.
• Use pattern matching for API response parsing and validation.

Formatting

• Use RuboCop for automated style enforcement.
• Use `.rubocop.yml` committed to the repository for project conventions.
• Max line length: 120 characters.
• Two-space indentation. No tabs.
• Use trailing commas in multi-line arrays and hashes.

Ruby Frameworks

Rails (General)

• Follow Rails conventions: convention over configuration.
• Use `rails generate` for scaffolding models, controllers, migrations.
• Use strong parameters: `params.require(:user).permit(:name, :email)`.
• Use concerns for shared controller/model behavior.
• Use `config/routes.rb` with resourceful routing: `resources :users`.
• Use environment-specific configuration in `config/environments/`.

ActiveRecord

• Use migrations for all schema changes. Never modify the database directly.
• Use `has_many`, `belongs_to`, `has_many :through` for associations.
• Use scopes for reusable query chains: `scope :active, -> { where(active: true) }`.
• Use `includes()` for eager loading to prevent N+1 queries.
• Use `find_each` for batch processing large record sets.
• Use `transaction` blocks for atomic multi-record operations.

ActionController

• Keep controllers thin: max 7 RESTful actions per controller.
• Use `before_action` for authentication and authorization checks.
• Use `respond_to` for content negotiation (JSON, HTML).
• Use `rescue_from` for centralized error handling in controllers.
• Use `render json:` with serializers (e.g., `ActiveModelSerializers`, `Blueprinter`).

Background Jobs

• Use Sidekiq for Redis-backed background job processing.
• Use ActiveJob as the abstraction layer over queue backends.
• Use `perform_later` for async execution. Use `perform_now` only in tests.
• Set `retry` count and `discard_on` / `retry_on` for error handling.
• Use `Sidekiq::Cron` or `clockwork` for scheduled recurring jobs.

Sinatra / Hanami

• Use Sinatra for lightweight APIs and microservices.
• Use Hanami for structured, modular Ruby web applications.
• Use Hanami actions (single-purpose) instead of fat controllers.
• Use Hanami repositories for data access abstraction.

API Mode

• Use `rails new --api` for API-only applications (no views, sessions).
• Use `Jbuilder` or `Blueprinter` for JSON serialization.
• Use `Rack::Attack` for rate limiting and throttling.
• Use versioned API namespaces: `namespace :v1 do ... end`.
• Use pagination with `kaminari` or `pagy` for collection endpoints.

Hotwire / Turbo

• Use Turbo Frames for partial page updates without JavaScript.
• Use Turbo Streams for real-time server-pushed DOM updates.
• Use Stimulus for lightweight JavaScript behavior on HTML elements.
• Keep JavaScript minimal: let the server render HTML.

Ruby Patterns

Error Handling

• Rescue specific exceptions. Never bare `rescue` (catches `StandardError`).
• Create domain exception hierarchies: `class AppError < StandardError; end`.
• Use `raise` with message and optional cause: `raise AppError, "msg"`.
• Use `retry` with a counter for transient failures.
• Use `ensure` for cleanup. Use `else` for code that runs only on success.

Service Objects

• Use single-purpose service classes with a `call` method.
• Use `Dry::Monads` Result type for operation outcomes.
• Return `Success(value)` or `Failure(error)` from service calls.
• Chain services with `bind` / `fmap` for pipeline composition.
• Keep services