simplifying-ruby-code

Original：🇺🇸 English

Translated

1 scripts

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.

7installs

Sourcebostonaholic/skills

Added on2026-11-01

NPX Install

npx skill4agent add bostonaholic/skills simplifying-ruby-code

SKILL.md Content

View Translation Comparison →

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

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.

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

Class-method-only classes to modules. A class never instantiated, defining only
```
self.
```
methods, becomes a module with
```
module_function
```
.
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.
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?
```
.
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 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.