design-patterns

Activation Contract

Load when selecting, applying, or reviewing a design pattern — creational, structural, behavioral, or system architecture (microservices, saga, CQRS, EDA). Applies to design work, architecture review, and implementation that adds abstractions. Read references/patterns-decision-guide.md for the full condensed tables before deciding.

Hard Rules

• Forces first: apply a pattern ONLY when the forces that motivate it are present. No pattern is correct for every problem.
• No pattern spamming / Golden Hammer: never apply a familiar pattern to everything. A "perfect, future-flexible" design you cannot justify today is over-design.
• Lightest route first: check the lightweight alternative (closures, optionals, direct calls, inheritance, plain functions) BEFORE adding indirection, extra classes, or a new abstraction layer.
• Singleton is the last resort: prefer dependency injection (container-scoped single instance). Global state breaks tests, hides dependencies, couples clients.
• Visitor is high-risk: it breaks encapsulation and every element-change ripples into all visitors. Use only for stable object structures (e.g. AST walks).
• Never design an anti-pattern intentionally: God Object, Spaghetti Code, Distributed Monolith, Shared Database, God Gateway, Chatty Communication are failure modes, not trade-offs.
• Every pattern adds complexity (classes, indirection, layers) — complexity is the cost you pay, so state the benefit explicitly in the artifact.

Decision Gates

Execution Steps

1. State the concrete problem and the forces present (variation axis, coupling to break, shared state, performance, scale).
2. Check the lightweight alternative table column first; if it suffices, stop and use it.
3. When a pattern survives, choose the minimal one that covers the forces — not the most elaborate family.
4. State the costs explicitly in the design artifact: extra classes/indirection/complexity, and why they pay off.
5. Check the anti-pattern list in references/patterns-decision-guide.md — reject any candidate that degenerates into one.
6. If a second pattern would cover the same forces, prefer the one with lower total complexity.

Output Contract

When a pattern is selected or rejected, record in the artifact: pattern name, forces present, lightweight alternative considered (and why rejected), costs added, and the anti-pattern(s) avoided. A rejection is a valid outcome — "no pattern" is a design decision.

References

• references/patterns-decision-guide.md — condensed tables: full problems, risks, and lightweight alternatives for each GoF + system architecture pattern; explicit anti-pattern catalog.