# code-design-patterns

> An open-source **Claude Skill for software design patterns**. It teaches Claude to choose, apply
> and — far more often — **refuse** design patterns. 115 pattern entries, 21 anti-patterns, a
> 10-dimension design rubric scored out of 30, and 30 canonical low-level design (LLD) problems.
> Plain Markdown, MIT licensed, no build step, no dependencies, no network calls.

The rule the skill enforces: **every pattern in the output must trace to a specific, stated force in
the requirements. If you cannot name the force, remove the pattern.**

Claude already knows the pattern catalogue. What it does not do reliably is decline to use it — so
designs arrive with a Singleton nobody asked for, a Factory wrapping `new`, and an Observer with no
subscribers, while the race condition in the allocation path goes unmentioned. This skill inverts
that default. Its main job is subtraction, not addition.

## Facts

- **Name:** code-design-patterns
- **Type:** Claude Skill (a `SKILL.md` folder); loadable by any agent that reads the `SKILL.md` convention
- **Version:** 1.2.0
- **License:** MIT — free for personal and commercial use
- **Repository:** https://github.com/00suryavanshi00/code-design-patterns
- **Website:** https://codedesignpatterns.dev
- **Contents:** 1 `SKILL.md` router + 11 reference files, 2,990 lines total
- **Covers:** 115 pattern entries · 21 anti-patterns · 30 LLD problems · a 10-dimension rubric
- **Dependencies:** none. No build step, no runtime, no telemetry, no network calls.

## Install

```
git clone https://github.com/00suryavanshi00/code-design-patterns.git
cp -r code-design-patterns/skill/code-design-patterns ~/.claude/skills/
```

Use `.claude/skills/` inside a repository for project scope, or `~/.claude/skills/` for every
project. On Claude.ai and Cowork, upload the folder under Settings → Capabilities → Skills.
A packaged single-file `.skill` bundle is in the repository's `dist/` folder.

## When Claude loads it

Automatically, whenever the work involves object-oriented or component design, class modelling,
low-level design or machine-coding problems ("design a parking lot / elevator / rate limiter"),
refactoring toward SOLID, reviewing a class design, structuring a new module or service, or any
question touching design patterns, architecture, extensibility, coupling or code smells — including
when the user never says the words "design pattern".

## What is inside

- [SKILL.md](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/SKILL.md): the 6-step workflow, the pattern tiers and the force→pattern routing table. The only file always in context.
- [01 · GoF catalogue](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/01-gof-catalog.md): all 23 Gang of Four patterns — intent, the force each resolves, real-codebase sightings, and the pairs everyone confuses (Strategy vs. State, Decorator vs. Proxy, Adapter vs. Facade).
- [02 · Architecture & application](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/02-modern-application-patterns.md): dependency injection without a container, repository without wrapping the ORM twice, hexagonal / ports and adapters, CQRS, event sourcing, result types, plugin systems, feature flags.
- [03 · Concurrency](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/03-concurrency-patterns.md): worker pools, pipelines, fan-out/fan-in, actors, the single-writer principle, compare-and-swap, backpressure, and the nine bugs reviewers look for.
- [04 · Distributed resilience](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/04-distributed-resilience-patterns.md): circuit breakers, deadline and retry budgets, hedged requests, bulkheads, five rate-limiting algorithms, sagas, the transactional outbox, distributed locks, sharding, strangler fig, expand-contract migration.
- [05 · Frontend components](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/05-frontend-patterns.md): compound components, custom hooks, provider splitting, props getters, state reducers, error boundaries, optimistic UI.
- [06 · Anti-patterns and smells](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/06-antipatterns-and-smells.md): 21 smells, each with a detectable signature and the smallest first refactoring move.
- [07 · Evaluation rubric](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/07-evaluation-rubric.md): 10 dimensions scored 0–3, out of 30, with automatic red flags that cap the total at 20 and a worked scored example.
- [08 · LLD question bank](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/08-lld-question-bank.md): 30 problems with the axis of change, the patterns that legitimately fit, the plausible wrong answer, and the probe that breaks a memorised one.
- [09 · Operability](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/09-operability.md): how to test and observe each pattern family, RED and USE signals, and what each costs to run.
- [10 · Persistence](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/10-persistence-patterns.md): optimistic vs. pessimistic locking, unique constraints and conditional writes, isolation levels and write skew, aggregates as transaction boundaries, idempotent writes, soft delete, multi-tenant isolation, read models, schema change.
- [11 · API contracts](https://github.com/00suryavanshi00/code-design-patterns/blob/main/skill/code-design-patterns/references/11-api-contract-patterns.md): error contracts, idempotent HTTP semantics, pagination, filtering, compatible evolution, versioning, deprecation, webhooks, contract tests.

## The tier system

Patterns are ranked by how often they are *actually the right answer* in production code, not by how
famous they are. The idea comes from Christopher Alexander's *A Pattern Language* (1977) — the book
the Gang of Four took the term "design pattern" from — which rated its 253 patterns with asterisks
for how confident Alexander was that each was a true invariant.

- **★★ Confident** — reach for these freely: Strategy, Factory Method, Builder, Adapter, Decorator, Observer, State, Template Method, Command, Iterator, Facade, Composite, Proxy, Dependency Injection, Repository, Middleware chain, Worker Pool, Circuit Breaker, Retry + jitter + budget, Expand-contract migration, Cache-aside, Idempotency Key, Value Object.
- **★ Situational** — right in specific conditions, suspicious otherwise: Abstract Factory, Chain of Responsibility, Visitor, Mediator, Bridge, Memento, Flyweight, Object Pool, Specification, Null Object, Unit of Work, CQRS, Event Sourcing, Saga, Actor, Bulkhead, Outbox, Leader Election, Hedged Requests, Single-writer / sharding.
- **· Doubtful** — usually a smell, needs an unusually good justification: Singleton, Prototype, Interpreter, Service Locator, Anemic Domain Model, hand-rolled double-checked locking, dual writes.

## Optional

- [llms-full.txt](https://codedesignpatterns.dev/llms-full.txt): the complete reference — the full rubric, every automatic red flag, all 30 LLD problems, the full anti-pattern list.
- [Website](https://codedesignpatterns.dev): the same material with a worked before/after example.