| name | kimchi:simplicity-enforcement |
| description | Use when designing solutions, implementing features, or considering abstractions. Enforces YAGNI, minimal code, and preferring duplication over wrong abstraction. |
Simplicity Enforcement
Overview
Complexity is the enemy. Every abstraction, configuration option, and "extensible" pattern is a cost. Pay it only when you must.
Core principle: Prefer simple solutions over clever ones. Always.
Violating the letter of these rules is violating the spirit of simplicity.
When This Applies
Every implementation decision. No exceptions.
The Iron Law
THE RIGHT AMOUNT OF COMPLEXITY IS THE MINIMUM NEEDED FOR THE CURRENT TASK
Three similar lines of code is better than a premature abstraction.
Principles
Prefer Duplication Over Wrong Abstraction
If you're not sure an abstraction is right:
- Duplicate the code
- Wait until you have 3+ similar cases
- Then extract with full understanding
```ruby
# Duplication when pattern unclear
class AvatarUploadService
def upload(file)
validate_size(file)
validate_type(file)
store_in_s3(file)
end
end
class DocumentUploadService
def upload(file)
validate_size(file)
validate_type(file)
store_in_s3(file)
end
end
Two cases. Let it sit. Extract when you see the third.
</Good>
<Bad>
```ruby
# Premature abstraction
class GenericUploadService
def initialize(validator:, storage:, processor: nil)
@validator = validator
@storage = storage
@processor = processor
end
def upload(file)
@validator.validate(file)
processed = @processor&.process(file) || file
@storage.store(processed)
end
end
Over-engineered for two use cases
YAGNI: You Aren't Gonna Need It
Don't build for hypothetical future requirements.
```ruby
# Build what's needed now
class ImageResizer
def resize(file, dimensions)
ImageProcessing::Vips
.source(file)
.resize_to_fill(*dimensions)
.call
end
end
```
```ruby
# Hypothetical future support
class ImageResizer
STRATEGIES = {
vips: VipsStrategy,
imagemagick: ImageMagickStrategy,
cloudinary: CloudinaryStrategy, # "in case we switch"
}
def initialize(strategy: :vips)
@strategy = STRATEGIES[strategy].new
end
end
</Bad>
### Hardcode First, Configure Later
If a value won't change soon, hardcode it.
<Good>
```ruby
AVATAR_SIZES = [32, 128, 512].freeze
BUCKET = 'avatars'
```ruby
config.avatar_sizes = [32, 128, 512] # In YAML config
config.avatar_bucket = ENV['AVATAR_BUCKET'] # When it's always 'avatars'
```
One Way to Do It
Don't provide multiple ways to accomplish the same thing.
```ruby
user.avatar_url(:medium)
```
```ruby
user.avatar_url
user.get_avatar_url
user.fetch_avatar(size: :medium)
Avatar.url_for(user)
```
Common Rationalizations
| Excuse | Reality |
|---|
| "We might need this later" | Build it later. YAGNI. |
| "It's more flexible this way" | Flexibility you don't need is complexity you pay for now. |
| "DRY says extract it" | DRY applies at 3+ repetitions with clear pattern, not 2. |
| "Enterprise patterns are best practice" | Factory/Strategy/Observer for one use case is anti-practice. |
| "Configuration makes it reusable" | Configuration for fixed values is noise. |
| "What if requirements change?" | They will. Refactor then, with full context. Cheaper than guessing now. |
| "It's only a little more complex" | Complexity compounds. Every "little" addition adds up. |
Red Flags — STOP and Simplify
- Writing a class with "Generic", "Base", or "Abstract" in the name for a single use
- Adding constructor parameters for "flexibility"
- Creating config files for values that won't change
- Writing a "factory" or "strategy" pattern
- Building plugin/extension points
- Adding feature flags for unrequested features
- Creating helpers/utilities for one-time operations
- Designing for hypothetical future requirements
ALL of these mean: STOP. Delete. Write the simple version.
Verification
Before completing:
Anti-Patterns
FORBIDDEN: "Enterprise" patterns for small features
Factory, Strategy, Observer, Visitor patterns are rarely needed. If you have one implementation, you don't need a pattern.
FORBIDDEN: Future-proofing
"What if we need to support X later?" — Build it later. You'll have more context then.
FORBIDDEN: DRY at all costs
Duplication is better than wrong abstraction. Two similar functions are fine. Extract at three.
FORBIDDEN: Backwards-compatibility shims
If something is unused, delete it. Don't rename to _var, re-export, or add # removed comments.
