home / skills / ratacat / claude-skills / design-patterns

design-patterns skill

needs review

This skill helps you apply design patterns to architect, refactor, and solve recurring problems with loose coupling and clear responsibilities.

npx playbooks add skill ratacat/claude-skills --skill design-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (21)

SKILL.md

9.7 KB

---
name: design-patterns
description: Use when designing software architecture, refactoring code structure, solving recurring design problems, or when code exhibits symptoms like tight coupling, rigid hierarchies, scattered responsibilities, or difficult-to-test components. Also use when choosing between architectural approaches or reviewing code for structural improvements.
---

# Design Patterns

## Overview

Design patterns are proven solutions to recurring software design problems. They provide a shared vocabulary for discussing design and capture collective wisdom refined through decades of real-world use.

**Core Philosophy:** Patterns are templates you adapt to your context, not blueprints to copy. Use the right pattern when it genuinely simplifies your design—not to impress or over-engineer.

## Foundational Principles

These principles underpin all good design:

| Principle | Meaning | Violation Symptom |
|-----------|---------|-------------------|
| **Encapsulate What Varies** | Isolate changing parts from stable parts | Changes ripple through codebase |
| **Program to Interfaces** | Depend on abstractions, not concretions | Can't swap implementations |
| **Composition Over Inheritance** | Build behavior by composing objects | Deep rigid class hierarchies |
| **Loose Coupling** | Minimize interdependency between objects | Can't change one thing without breaking another |
| **Open-Closed** | Open for extension, closed for modification | Must edit existing code for new features |
| **Single Responsibility** | One reason to change per class | Classes doing too many things |
| **Dependency Inversion** | High-level modules don't depend on low-level | Business logic coupled to infrastructure |

## Pattern Selection Guide

### By Problem Type

```
CREATING OBJECTS
├── Complex/conditional creation ──────────→ Factory Method
├── Families of related objects ───────────→ Abstract Factory
├── Step-by-step construction ─────────────→ Builder
├── Clone existing objects ────────────────→ Prototype
└── Single instance needed ────────────────→ Singleton (use sparingly!)

STRUCTURING/COMPOSING OBJECTS
├── Incompatible interface ────────────────→ Adapter
├── Simplify complex subsystem ────────────→ Facade
├── Tree/hierarchy structure ──────────────→ Composite
├── Add behavior dynamically ──────────────→ Decorator
└── Control access to object ──────────────→ Proxy

MANAGING COMMUNICATION/BEHAVIOR
├── One-to-many notification ──────────────→ Observer
├── Encapsulate requests as objects ───────→ Command
├── Behavior varies by internal state ─────→ State
├── Swap algorithms at runtime ────────────→ Strategy
├── Algorithm skeleton with hooks ─────────→ Template Method
├── Reduce N-to-N communication ───────────→ Mediator
└── Sequential handlers ───────────────────→ Chain of Responsibility

MANAGING DATA ACCESS
├── Abstract data source ──────────────────→ Repository
├── Track changes for atomic commit ───────→ Unit of Work
├── Ensure object identity ────────────────→ Identity Map
├── Defer expensive loading ───────────────→ Lazy Load
├── Map objects to database ───────────────→ Data Mapper
└── Shape data for transfer ───────────────→ DTO
```

### By Symptom

| Symptom | Consider |
|---------|----------|
| Giant switch/if-else on type | Strategy, State, or polymorphism |
| Duplicate code across classes | Template Method, Strategy |
| Need to notify many objects of changes | Observer |
| Complex object creation logic | Factory, Builder |
| Adding features bloats class | Decorator |
| Third-party API doesn't fit your code | Adapter |
| Too many dependencies between components | Mediator, Facade |
| Can't test without database/network | Repository, Dependency Injection |
| Need undo/redo | Command |
| Object behavior depends on state | State |
| Request needs processing by multiple handlers | Chain of Responsibility |

### Domain Logic: Transaction Script vs Domain Model

| Factor | Transaction Script | Domain Model |
|--------|-------------------|--------------|
| Logic complexity | Simple (< 500 lines) | Complex, many rules |
| Business rules | Few, straightforward | Many, interacting |
| Operations | CRUD-heavy | Rich behavior |
| Team/timeline | Small team, quick delivery | Long-term maintenance |
| Testing | Integration tests | Unit tests on domain |

**Rule of thumb:** Start with Transaction Script. Refactor to Domain Model when procedural code becomes hard to maintain.

## Quick Reference

### Tier 1: Essential Patterns (Master First)

| Pattern | One-Line | When to Use | Reference |
|---------|----------|-------------|-----------|
| **Strategy** | Encapsulate interchangeable algorithms | Multiple ways to do something, swap at runtime | [strategy.md](patterns/strategy.md) |
| **Observer** | Notify dependents of state changes | Event systems, reactive updates | [observer.md](patterns/observer.md) |
| **Factory** | Encapsulate object creation | Complex/conditional instantiation | [factory.md](patterns/factory.md) |
| **Decorator** | Add behavior dynamically | Extend without inheritance | [decorator.md](patterns/decorator.md) |
| **Command** | Encapsulate requests as objects | Undo/redo, queuing, logging | [command.md](patterns/command.md) |

### Tier 2: Structural Patterns

| Pattern | One-Line | When to Use | Reference |
|---------|----------|-------------|-----------|
| **Adapter** | Convert interfaces | Integrate incompatible code | [adapter.md](patterns/adapter.md) |
| **Facade** | Simplify complex subsystems | Hide complexity behind simple API | [facade.md](patterns/facade.md) |
| **Composite** | Uniform tree structures | Part-whole hierarchies | [composite.md](patterns/composite.md) |
| **Proxy** | Control access to objects | Lazy load, access control, caching | [proxy.md](patterns/proxy.md) |

### Tier 3: Enterprise/Architectural Patterns

| Pattern | One-Line | When to Use | Reference |
|---------|----------|-------------|-----------|
| **Repository** | Collection-like data access | Decouple domain from data layer | [repository.md](patterns/repository.md) |
| **Unit of Work** | Coordinate atomic changes | Transaction management | [unit-of-work.md](patterns/unit-of-work.md) |
| **Service Layer** | Orchestrate business operations | Define application boundary | [service-layer.md](patterns/service-layer.md) |
| **DTO** | Shape data for transfer | API contracts, prevent over-exposure | [dto.md](patterns/dto.md) |

### Additional Important Patterns

| Pattern | One-Line | When to Use | Reference |
|---------|----------|-------------|-----------|
| **Builder** | Step-by-step object construction | Complex objects, fluent APIs | [builder.md](patterns/builder.md) |
| **State** | Behavior changes with state | State machines, workflow | [state.md](patterns/state.md) |
| **Template Method** | Algorithm skeleton with hooks | Framework extension points | [template-method.md](patterns/template-method.md) |
| **Chain of Responsibility** | Pass request along handlers | Middleware, pipelines | [chain-of-responsibility.md](patterns/chain-of-responsibility.md) |
| **Mediator** | Centralize complex communication | Reduce component coupling | [mediator.md](patterns/mediator.md) |
| **Lazy Load** | Defer expensive loading | Performance, large object graphs | [lazy-load.md](patterns/lazy-load.md) |
| **Identity Map** | Ensure object identity | ORM, prevent duplicates | [identity-map.md](patterns/identity-map.md) |

## Common Mistakes

| Mistake | Symptom | Fix |
|---------|---------|-----|
| **Pattern Overuse** | Simple operations require navigating many classes | Only use when solving real problem |
| **Wrong Pattern** | Code feels forced, awkward | Re-examine actual problem |
| **Inheritance Abuse** | Deep hierarchies, fragile base class | Favor composition (Strategy, Decorator) |
| **Singleton Abuse** | Global state, hidden dependencies, hard to test | Use dependency injection instead |
| **Premature Abstraction** | Interfaces with single implementation | Wait for real need to vary |

## Anti-Patterns to Recognize

- **God Object:** One class does everything → Split using SRP
- **Anemic Domain Model:** Objects are just data bags → Move behavior to objects
- **Golden Hammer:** Same pattern everywhere → Match pattern to problem
- **Lava Flow:** Dead code nobody removes → Delete it, VCS has your back

## Modern Variations

| Modern Pattern | Based On | Description |
|----------------|----------|-------------|
| **Dependency Injection** | Strategy + Factory | Container creates and injects dependencies |
| **Middleware** | Decorator + Chain of Responsibility | Request/response pipeline |
| **Event Sourcing** | Command | Store state changes as events |
| **CQRS** | Command/Query separation | Separate read/write models |
| **Hooks (React/Vue)** | Observer + Strategy | Functional lifecycle subscriptions |

## Implementation Checklist

Before implementing a pattern:

- [ ] Pattern solves a real problem in this codebase
- [ ] Considered simpler alternatives
- [ ] Trade-offs acceptable for this context
- [ ] Team understands the pattern
- [ ] Won't over-engineer the solution

Overview

This skill helps you choose and apply proven design patterns when designing software architecture, refactoring code, or diagnosing structural problems. It emphasizes practical selection based on symptoms, trade-offs, and the principle that patterns are templates to adapt, not rigid blueprints. Use it to reduce coupling, improve testability, and clarify component responsibilities.

How this skill works

The skill inspects code smells and symptoms—like giant switch statements, tight coupling, deep inheritance, or hard-to-test modules—and maps them to appropriate patterns (e.g., Strategy, Factory, Repository). It guides pattern selection by problem type and symptom, highlights foundational principles (SRP, composition over inheritance, dependency inversion), and offers modern variations and anti-pattern warnings. It also provides a short implementation checklist to validate a pattern before applying it.

When to use it

Designing or refactoring architecture to reduce coupling or improve modularity
When code shows symptoms: giant switch/if-else, rigid hierarchies, duplicated logic, or hard-to-test components
Choosing between architectural approaches (Transaction Script vs Domain Model)
Integrating third-party APIs or simplifying complex subsystems
Defining data access boundaries or improving transactional behavior

Best practices

Start from the actual problem—prefer simpler alternatives before introducing a pattern
Favor composition and interfaces over inheritance to keep designs flexible
Document the trade-offs and ensure the team understands the pattern’s intent
Avoid premature abstraction; only introduce interfaces when variation is expected
Prefer dependency injection over singletons to keep components testable

Example use cases

Replace a giant switch handling behavior types with Strategy or State to make adding behaviors easy
Wrap a complex subsystem with a Facade to simplify client code and reduce coupling
Introduce Repository and Unit of Work to decouple domain logic from persistence and enable easier testing
Apply Decorator to add cross-cutting functionality (logging, caching) without altering core classes
Use Adapter to integrate an incompatible third-party API without spreading changes across the codebase

FAQ

When should I refactor Transaction Script into a Domain Model?

Refactor when business rules grow complex, operations become interdependent, and procedural code exceeds maintainability; start small and migrate where the domain warrants unit-testable, behavior-rich objects.

How do I avoid pattern overuse?

Only apply a pattern when it directly addresses a measurable problem, evaluate simpler solutions first, and verify trade-offs with the team before introducing added complexity.