CLAUDE.md for Ruby: 13 Rules That Make AI Write Idiomatic, Production-Ready Ruby

Ruby version: 3.3+. Use YJIT in production (`RUBY_YJIT_ENABLE=1` or `--yjit`).
Bundler manages all gems — no manual `require` for anything in the Gemfile.
`.ruby-version` file is authoritative for local development.

Prefer trailing conditionals for single-line guards:
  `return if invalid?` not `if invalid? then return end`
  `notify! unless silent?` not `if !silent? then notify! end`

Use ternary only for simple value selection:
  `status = active? ? :online : :offline`

Avoid nested ternaries — extract to a method instead.

Hash keys: use symbols for internal data structures.
  `{ name: "Alice", role: :admin }` not `{ "name" => "Alice", "role" => "admin" }`

String keys only when the key comes from external input (JSON parsing, HTTP params) or when
the key must be dynamic.

Use `Hash#fetch` with a default or block when the key might be absent:
  `config.fetch(:timeout, 30)` not `config[:timeout] || 30`

Blocks: for one-off iteration and DSL construction (`each`, `map`, `tap`, `yield`).
Lambdas (`-> {}`): when you need to store callable behavior, check arity, or return from within.
Procs (`proc {}`): rarely — only when you explicitly need loose arity behavior.

Prefer `&method(:name)` over a block that just calls a method:
  `users.map(&method(:transform))` not `users.map { |u| transform(u) }`

Use `Symbol#to_proc` for simple field extraction:
  `names.map(&:upcase)` not `names.map { |n| n.upcase }`

Use Enumerable methods instead of index-based loops:
- `map` / `flat_map` for transformations
- `select` / `reject` for filtering
- `reduce` / `each_with_object` for aggregation
- `find` for first match
- `group_by`, `tally`, `chunk_while` for grouping
- `any?`, `all?`, `none?`, `count` for predicates

Never use `for` loops — use `each`.
Avoid `inject(:+)` when `sum` is available.

Use `attr_reader`, `attr_writer`, `attr_accessor` instead of manual getter/setter methods.
Mark methods private when they're implementation details — default to private, not public.
Use `protected` only for methods called by instances of the same class (rare).

Order in class body: class methods → initialize → public instance methods → private methods.
Separate sections with `private` keyword, not comments.

Error handling:
- Rescue `StandardError` or specific subclasses — never `Exception`
  (`Exception` catches `SignalException`, `Interrupt`, `NoMemoryError` — almost always wrong)
- Prefer inline rescue for simple defaults: `value = risky_call rescue default_value`
  (only when the rescue is genuinely a simple fallback, not for flow control)
- Use `ensure` for cleanup, not rescue blocks
- Custom exceptions: inherit from `StandardError`, name with `Error` suffix
  `class PaymentFailedError < StandardError; end`
- Raise with a message: `raise PaymentFailedError, "Card declined: #{reason}"`

Add `# frozen_string_literal: true` at the top of every Ruby file.
This makes all string literals immutable and reduces object allocation.

When a mutable string is genuinely needed: `String.new("mutable")` or `+"mutable"`.
Use string interpolation (`"#{var}"`) over concatenation (`str + other`).
Prefer `<<` (shovel) for in-place string building only when mutation is intentional and documented.

If this is a Rails project:

- Fat models, thin controllers — business logic belongs in models or service objects
- Service objects in `app/services/` for operations that cross model boundaries
- Scopes over class methods for chainable queries: `scope :active, -> { where(active: true) }`
- `find_each` / `in_batches` for large dataset iteration — never `.all.each`
- Avoid N+1: use `includes`, `eager_load`, or `preload` — add Bullet gem to detect
- Strong parameters in controllers, not models
- `before_action` for authentication/authorization, not inline checks
- No raw SQL — use Arel or query interface; raw SQL only with `sanitize_sql`

Testing: RSpec with FactoryBot for fixtures.

- Describe behavior, not implementation: `describe '#charge'` not `describe 'PaymentsController line 42'`
- Use `let` and `let!` for setup — not instance variables in `before` blocks
- `subject` for the object under test
- One assertion per example (generally) — exceptions: related state changes
- `context` blocks for branching: `context 'when payment fails'`
- Shared examples for common behavior across multiple classes
- `described_class` over hardcoded class names in specs
- VCR or WebMock for external HTTP — never hit real APIs in tests

Prefer module mixins over inheritance for shared behavior:
  `include Auditable` not `class User < AuditableBase`

Use dependency injection for external services:
  `def initialize(mailer: UserMailer)` not `UserMailer.deliver` inside methods

Avoid monkey-patching core classes — use refinements (`refine String do`) when extension is necessary.
No `method_missing` without `respond_to_missing?`.

Use pattern matching for complex conditional dispatch:

  case response
  in { status: 200, body: { user: { id: Integer => id } } }
    process_user(id)
  in { status: 422, errors: [*, String => first_error, *] }
    handle_validation_error(first_error)
  in { status: (400..499) }
    handle_client_error(response)
  end

Use `in` (one-armed pattern match) for destructuring:
  `response => { user: { name:, email: } }`

Gemfile conventions:
- Pin major versions for stability: `gem 'rails', '~> 7.1'`
- Group gems correctly: `:development`, `:test`, `:development, :test`
- `bundle audit` before any update — check for security advisories
- No gems with `require: false` unless you manually require them
- Prefer gems with active maintenance — check last commit date on GitHub before adding
- Lock Ruby version in Gemfile: `ruby '~> 3.3'`

# Ruby Project — AI Coding Rules

## Runtime
Ruby 3.3+. frozen_string_literal: true on every file.

## Style
- Trailing conditionals for guards: `return if invalid?`
- Symbols for internal hash keys
- Enumerable over loops: map/select/reduce/find
- &:method_name and &method(:name) over verbose blocks

## Error Handling
rescue StandardError (specific subclasses preferred). Never rescue Exception.
Custom errors inherit StandardError, named with Error suffix.

## Architecture
attr_reader/writer/accessor over manual getters/setters.
Private by default — public only what callers need.
Service objects in app/services/ for cross-model operations.

## Rails (if applicable)
Fat models, thin controllers. Scopes for chainable queries.
find_each for large sets. includes/eager_load to prevent N+1.

## Testing
RSpec + FactoryBot. let/let! for setup. One assertion per example.
context blocks for branching. VCR/WebMock for external HTTP.

## Dependencies
bundle audit on every update. Pin major versions.