# Simplifying Ruby Code

> Rewrites over-engineered Ruby and Rails classes (stateless service objects, behaviorless value objects, class-method-only classes, deep inheritance, needless metaprogramming) as Data, Struct, Hash, modules, or pure functions, after finding every caller and getting a green test baseline, or reports findings when asked to review. Use when the user says "simplify this Ruby", or when asked to refactor, simplify, review, or cut boilerplate from a Ruby or Rails class, value object, service object, gem, or branch diff (hand-written initialize, readers, ==, eql?, or hash; call-only classes; Struct vs Data), or when tests need heavy mocking. Not for a broad Rails tech-debt audit; use auditing-rails-tech-debt.

- Skill: `bostonaholic/simplifying-ruby-code` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add bostonaholic/simplifying-ruby-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bostonaholic/simplifying-ruby-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: bostonaholic (https://skillmd.com/u/bostonaholic)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/bostonaholic/simplifying-ruby-code

---


# Simplifying Ruby Code

Prefer plain data (Hash, Array, Struct, Data) and pure functions over classes
that add no state or behavior. Separate decisions from effects: a decision
takes data and returns data; an effect does I/O (database, network, files,
time). Keep them in separate methods or modules so decisions test without
mocks.

When the user asks for a review, report findings and edit nothing unless
they ask. Cite patterns by number ("Pattern 1") or by anti-pattern name.

## Patterns

1. **Command objects to module functions.** A class whose only public
   method is `call`, `perform`, `run`, or `execute`, holding nothing beyond
   its constructor arguments, becomes a direct call or a module function
   (`UserCreator.new(params).call` becomes `User.create(params)`). Keep the
   object when it holds state across calls, runs a multi-step algorithm
   worth naming, or must be serialized, as a background job is.
2. **Value objects to Data, Struct, or Hash.** A class that only stores
   attributes, with hand-written `initialize`, readers, or `==` and no
   behavior or validation:

   | Use          | When                                                 |
   | ------------ | ---------------------------------------------------- |
   | Hash         | Transient data, varying keys, JSON in or out         |
   | Struct       | Fixed attributes, mutation acceptable                |
   | Data         | Fixed attributes, immutable (check `ruby -v` >= 3.2) |
   | Custom class | Validation, invariants, or real domain behavior      |

3. **Class-method-only classes to modules.** A class never instantiated,
   defining only `self.` methods, becomes a module with `module_function`.
4. **Deep inheritance to composition.** More than 2 levels counting only the
   project's own classes (framework and stdlib bases such as
   `ApplicationRecord` or `StandardError` do not count), or an abstract base
   with a single subclass.
5. **Missing Ruby protocols.** Callers unpack a collection-like or
   value-like class by hand instead of it implementing `each` with
   `Enumerable`, `to_h`, `<=>` with `Comparable`, or `hash` and `eql?`.
6. **Mixed decisions and effects.** Tests need heavy mocks, or a method
   computes and writes in one body. Extract the computation into a pure
   function and leave a thin method for the I/O.

## Rails anti-patterns

- **Service objects:** a single-method, stateless service belongs in a model
  method or module function (Pattern 1). Keep complex orchestration as a
  service but separate decisions from effects (Pattern 6). Jobs are
  legitimate objects because they serialize.
- **Models:** keep ActiveRecord models as classes; move business
  calculations into pure functions.
- **Concerns:** a concern shares behavior across models; flag one used as a
  dumping ground for a single model.
- **Helpers:** view formatting only; business rules go in a module.
- **Reinvented Rails:** custom DSLs or base classes that duplicate scopes,
  validations, callbacks, enums, or `ActiveModel`.

## Plain Ruby anti-patterns

- **Template methods:** a base class with hook methods where a block would do.
- **Builders:** for objects that keyword arguments or `Data.define` build
  directly.
- **Wrappers:** classes that wrap Array, Hash, Set, or another stdlib type
  and forward most calls.
- **Metaprogramming:** `method_missing`, `define_method`, or `instance_eval`
  DSLs where plain methods work.
- **Dependencies:** a gem pulled in for a few lines of stdlib code.

In a gem, every public constant is API that other projects may call.

## Before removing or inlining a class

- Run `bash <skill-dir>/scripts/find-callers.sh <Constant> <project>` for
  each class.
- Exit 0: account for every `reference` and `require` hit, and decide for
  each `dynamic` hit whether the name it builds can be the class; that takes
  reading the code, so it stays with you.
- Exit 1: no caller found. Exit 2: fix the argument. Exit 3: install the
  named tool. Exit 4: report the grep error.
- A controller is also reached from `config/routes.rb` by its snake_case
  resource name, which the script does not search; read that file.
- In a review, drop or downgrade a finding whose callers you cannot account
  for.

## Review findings

Read [review findings](references/review-findings.md) when reporting a
review: the grouping, the fields of each finding, and the closing order.

## Refactoring

Get a green test baseline first. Apply one pattern at a time and run the
suite after each; on failure, fix or revert that step before continuing.
Update tests that mocked the removed layer to call the pure function or the
direct API instead.

