---
name: aipatterns-design-patterns
description: Implement the 22 classic GoF design patterns in TypeScript, Python, Go or Java. Each pattern gives its forces, structure, steps, trade-offs and "do not use it when" rules. Use before you implement, review or explain a pattern such as Factory Method, Abstract Factory, Builder, Prototype, Singleton, Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy, Chain of Responsibility, Command, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method or Visitor. Also covers patterns original to the reference - resilience (Timeout, Retry, Exponential Backoff, Circuit Breaker, Fallback, Rate Limiting), data (Cache-Aside, Transactional Outbox, Saga, Idempotent Consumer, CQRS) and architecture (Strangler Fig, Backends for Frontends). Not for behavior changes or when a language feature covers the variance - run aipatterns-pattern-selection first.
license: MIT
metadata:
  source: https://aipatterns.dev/design-patterns
  version: "1.0.0"
---

# Design patterns

Use this skill after you choose a pattern. If you have not checked that you need a pattern, run the `aipatterns-pattern-selection` procedure first. If no current pain forces the pattern, stop: write the simplest code and add nothing.

## Workflow

1. Open the pattern's reference file (table below) and read, in order: **Do not use it when**, then **Forces**, then **Therefore**.
2. If any "Do not use it when" bullet matches the situation, stop and use the simpler alternative it names.
3. Map the pattern's participants to real names in the codebase. Use domain names, never the pattern's role names (`ShippingStrategy`, not `StrategyImpl`).
4. **Grill the application first** (the `aipatterns-grill` skill, or the MCP tool `grill_pattern`): inspect the code and existing infrastructure, identify what is missing, and settle scale, performance, reliability, budget and implementation questions with the user.
5. Follow **Implementation steps**. Keep the existing tests green after every step.
6. Write the idiomatic form for the language:
   - **TypeScript / Python:** prefer functions and protocols over class hierarchies when a role has one method.
   - **Go:** use small interfaces satisfied implicitly, and embed structs instead of inheriting. Function types (`type QuoteFunc func(Order) int`) can satisfy an interface.
   - **Java:** use records, sealed interfaces and lambdas (`@FunctionalInterface`) where they shorten the pattern.
7. Run the pattern's **Agent checklist** before you finish. Name the pattern in your summary, with the reason you chose it.

## Catalogue

**Creational**: how code creates objects.

- [Factory Method](references/factory-method.md): subclasses or functions decide which product to create.
- [Abstract Factory](references/abstract-factory.md): create matched families of related objects.
- [Builder](references/builder.md): assemble a complex object step by step.
- [Prototype](references/prototype.md): create objects by copying a configured instance.
- [Singleton](references/singleton.md): one instance per process. Usually inject it instead.

**Structural**: how objects fit together.

- [Adapter](references/adapter.md): make an existing interface fit the one you need.
- [Bridge](references/bridge.md): separate two dimensions of variation.
- [Composite](references/composite.md): treat leaves and groups uniformly in a tree.
- [Decorator](references/decorator.md): add behavior by wrapping, without subclassing.
- [Facade](references/facade.md): one simple entry point over a subsystem.
- [Flyweight](references/flyweight.md): share common state across many small objects.
- [Proxy](references/proxy.md): stand in for an object to control access.

**Behavioral**: how objects divide work and communicate.

- [Chain of Responsibility](references/chain-of-responsibility.md): pass a request along handlers.
- [Command](references/command.md): turn a request into an object that can be queued, logged or undone.
- [Iterator](references/iterator.md): traverse a collection without exposing its layout.
- [Mediator](references/mediator.md): centralize communication between components.
- [Memento](references/memento.md): snapshot and restore state without breaking encapsulation.
- [Observer](references/observer.md): notify subscribers of changes.
- [State](references/state.md): change behavior when internal state changes.
- [Strategy](references/strategy.md): swap interchangeable algorithms behind one interface.
- [Template Method](references/template-method.md): a fixed workflow with overridable steps.
- [Visitor](references/visitor.md): add operations over a stable set of node types.

**Resilience**: for calls that can fail, hang or come back wrong.

- [Timeout](references/timeout.md): bound every remote call with a deadline.
- [Retry](references/retry.md): repeat only retryable, repeatable operations.
- [Exponential Backoff](references/exponential-backoff.md): space the repeats; add jitter.
- [Circuit Breaker](references/circuit-breaker.md): stop calling a dependency that is down.
- [Fallback](references/fallback.md): serve a lesser answer so the journey continues.
- [Rate Limiting](references/rate-limiting.md): budget calls per client; refuse with Retry-After.

**Data**: keep shared data honest at speed and across services.

- [Cache-Aside](references/cache-aside.md): cache on miss, evict on write; the store stays the truth.
- [Transactional Outbox](references/transactional-outbox.md): the message is a row in the business transaction; a relay publishes.
- [Saga](references/saga.md): local steps with compensations, undone in reverse on failure.
- [Idempotent Consumer](references/idempotent-consumer.md): claim the message id in the work's transaction; duplicates skip.
- [CQRS](references/cqrs.md): commands on one model, queries on per-view read models, joined by projections.

**Architecture**: boundaries measured in routes and releases.

- [Strangler Fig](references/strangler-fig.md): route through a facade, replace handlers one route at a time.
- [Backends for Frontends](references/backends-for-frontends.md): one aggregation backend per client; services know no client.

Category overviews: [creational](references/creational.md), [structural](references/structural.md), [behavioral](references/behavioral.md), [resilience](references/resilience.md), [data](references/data.md), [architecture](references/architecture.md).

## Non-negotiables

- Never introduce a pattern without a named, current pain.
- Never ship a pattern with a single concrete implementation unless the second one is in the same change.
- Never change behavior while restructuring. Refactor first, then extend in a separate step.
- Prefer composition over inheritance unless the pattern explicitly needs inheritance (Template Method), and even then consider a function parameter.

Every reference is also served at `https://aipatterns.dev/design-patterns/<slug>.md` and through the MCP server at `https://aipatterns.dev/mcp`.