ruby-object-design_skill

Overview

This skill helps you choose the right Ruby construct—class, module, Struct/Data, or Hash—by applying the principle that Ruby is object-oriented, not class-oriented. It discourages reflexively using class as the default and focuses on objects and messages. The guidance is practical and targeted at design decisions, refactors, and reviews to reduce boilerplate and over-engineering.

How this skill works

When triggered it inspects intent: whether multiple instances with encapsulated state are required, whether behavior accompanies that state, or whether the code is stateless utility or simple data. It applies a decision tree (class for object factories; module for stateless utilities; Struct/Data for simple data containers; Hash for ad-hoc groups) and flags common 'class smells'. Recommendations include concrete before/after patterns and a safe migration path.

When to use it

• Deciding between class, module, Struct/Data, or Hash for a new component
• Reviewing code that has many single-method or stateless classes
• Refactoring pattern-named classes (Factory, Builder, Decorator) to simpler Ruby idioms
• Designing features where object validity at construction matters
• Converting boilerplate POROs into Structs or Data objects

Best practices

• Only use class when you need an object factory: multiple instances with state + behavior
• Prefer module with extend self for stateless utility collections and namespacing
• Use Struct or Ruby 3.2+ Data for simple data containers and immutable value objects
• Avoid single-method service classes; prefer module functions or plain methods when state is unnecessary
• Ensure objects are valid immediately after .new; require needed data in initialize

Example use cases

• A Policy domain object with state and behavior → keep as a class (object factory)
• String utility methods currently in a class with only class methods → convert to module with extend self
• A simple DTO used to pass attributes around → use Struct or Data instead of a full class
• A CalculateDiscount service with only call → replace with module function or plain method
• Legacy Report class requiring setters after .new → make constructor accept required data so object is valid at birth