Skip to content

swell-agents/coding-skills / skills/designing-architecture

designing-architecture

Verified

reference/pattern-catalogue.md

View on GitHub
---
purpose: Compact design pattern catalogue with applicability tests, used during pattern selection in designing-architecture
---

# Pattern catalogue

Patterns grouped by Gang-of-Four category and architectural scope. Each entry is the *applicability test* — when a pattern earns its keep — not the implementation. For implementation, see Refactoring.guru.

The skill applies the **YAGNI test** to every selection: if you can't articulate the concrete problem the pattern solves in the current feature, don't use it. Pattern tourism creates indirection without value.

## Creational

- **Factory Method** — *use when* construction logic depends on a runtime decision (subtype/config) and you want callers to be agnostic to it. *Don't use when* there's only one product type — direct instantiation is simpler.
- **Abstract Factory** — *use when* you need families of related products that vary together (UI widget kit per OS). Rare outside cross-platform code.
- **Builder** — *use when* an object has many optional parameters and a phased construction (HTTP request builders, query builders).
- **Singleton** — *use when* state is genuinely global (process-wide config, connection pool). *Don't use as* a global-variable convenience; it kills testability.
- **Prototype** — *use when* cloning is materially cheaper than reconstructing.

## Structural

- **Adapter** — *use when* an existing implementation has the right behaviour but the wrong interface. Common when wrapping third-party libraries.
- **Bridge** — *use when* an abstraction and its implementation should vary independently. The classic case is multiple persistence backends behind one repository interface.
- **Composite** — *use when* clients should treat individual objects and compositions of them uniformly (filesystem trees, UI component hierarchies).
- **Decorator** — *use when* you need to add behaviour to instances at runtime without subclass explosion (logging, caching, retry around an HTTP client).
- **Facade** — *use when* a subsystem has a complex API and most callers only need a slice of it.
- **Flyweight** — *use when* you have huge numbers of nearly-identical objects and memory is bounded.
- **Proxy** — *use when* the real subject is expensive to access (lazy loading, remote calls) or you need access control / instrumentation around it.

## Behavioural

- **Chain of Responsibility** — *use when* a request should be processed by one of several handlers and the choice is dynamic (middleware pipelines).
- **Command** — *use when* you need to parameterise actions (undo/redo, queued operations, RPC).
- **Iterator** — language-built-in in most modern languages; rarely an explicit pattern decision.
- **Mediator** — *use when* component-to-component communication has become a graph; centralise it through a mediator.
- **Memento** — *use when* you need snapshots without exposing internals (undo systems, transactional rollback).
- **Observer** — *use when* one object's state change should notify many others; consider event-bus / pub-sub at scale.
- **State** — *use when* an object's behaviour depends on a state machine and the state count is non-trivial.
- **Strategy** — *use when* an algorithm has interchangeable variants chosen at runtime (sort comparator, compression algorithm, retry policy).
- **Template Method** — *use when* a multi-step algorithm has fixed structure but variable steps. Often replaced by Strategy + composition; favour composition.
- **Visitor** — *use when* you need to add operations to a stable type hierarchy without modifying the types. Heavy machinery; reach for it only when other options have failed.

## Domain (DDD)

- **Repository** — *use when* persistence concerns should be hidden from the domain. The collection-like interface (`add`, `remove`, `find_by_id`) is the test; if your "repository" has 30 query methods, it's actually a DAO.
- **Unit of Work** — *use when* multiple repository operations should commit or rollback as one transaction.
- **Specification** — *use when* domain queries grow combinatorially (filter rules, eligibility checks); composable specs avoid `if`-tree sprawl.
- **Value Object** — *use when* an attribute is defined by its value and is immutable (Money, EmailAddress, GeoCoordinate). Replaces primitive-obsession smells.
- **Entity** — *use when* identity matters across changes (User, Order). Entities have ID; value objects don't.
- **Domain Event** — *use when* something domain-meaningful happened that other parts of the system care about (`OrderPaid`, `UserDeactivated`). Pairs with the Outbox pattern for reliability.

## Architectural

- **Hexagonal / Ports-and-Adapters** — *use when* the domain should be independent of frameworks, databases, and transport. Default for non-trivial services.
- **Pipes & Filters** — *use when* a stream of data passes through stateless transformations (ETL, log processing).
- **Event-Driven** — *use when* services communicate asynchronously and the producer doesn't care who consumes. Pairs with message brokers.
- **CQRS** — *use when* read and write models diverge enough that one schema can't serve both well. Adds operational complexity; don't reach for it lightly.
- **Saga** — *use when* a long-running business transaction spans multiple services and must be coordinated with compensating actions.
- **Outbox** — *use when* a domain event must be published reliably alongside a database commit. The transactional outbox + relay is the canonical fix for "I dispatched the event but the DB rolled back."
- **Strangler Fig** — *use when* replacing a legacy system incrementally. The new system shadows the old until the old can be deleted.
- **Branch by Abstraction** — *use when* a long-running internal change should ship behind an interface so trunk stays releasable.

## Quick selection heuristics

- **Two implementations of the same thing chosen at runtime** → Strategy.
- **Optional cross-cutting wrapping** → Decorator.
- **Hide a complex collaborator** → Facade or Adapter.
- **Persistence behind a clean interface** → Repository (and Unit of Work for batched commits).
- **Multi-step business transaction across services** → Saga + Outbox.
- **Rich state-dependent behaviour on one object** → State.
- **Add operations to a closed hierarchy** → Visitor (last resort).
- **Cross-cutting concerns on every request** → Chain of Responsibility (middleware).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall