# 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.

## What changes, concretely

Asked to "design a parking lot":

**Without the skill**

- Singleton ParkingLotManager , unexplained
- VehicleFactory over classes that differ by one enum
- Fees as double ; the clock called inline
- Concurrency waved at — “add a lock”
- Patterns listed, never justified
- Nothing on how you would know it broke in production

**With the skill**

- Axis of change named before a class is written
- Allocation and pricing split — they change for different reasons
- Claiming a spot is one atomic op : CAS, not check-then-act
- Money value object; Clock injected
- Pattern ledger: force resolved, alternative rejected
- One metric per pattern , and what would page someone

## The evaluation rubric

Ten dimensions, scored 0-3, total out of 30. Below 20 the skill revises rather than presents. Any single zero is a blocker.

01. **Requirements fidelity** — Requirements enumerated and traceable; ambiguities named rather than silently resolved.
02. **Responsibility allocation** — Boundaries follow reasons for change, not merely topic similarity.
03. **Extensibility on the stated axis** — Adding the likely variant touches two files or fewer — demonstrated, not claimed.
04. **Interface quality** — Minimal, consumer-owned, hard to misuse. Illegal states unrepresentable.
05. **Pattern selection** — Caps at 1 if any pattern cannot be traced to a stated requirement.
06. **Concurrency correctness** — What is shared, what the atomic unit is, and no lock held across I/O.
07. **Failure handling** — Partial failure reasoned about: what is idempotent, what compensates, what the caller sees.
08. **Testability & observability** — Clock and randomness injected; and one metric per breaker, queue or cache, with what would page someone.
09. **Data modelling** — Invariants enforced at construction; persistence shape not dictating domain shape.
10. **Trade-off communication** — States what the design is bad at, and what the simpler version would have been.

### Automatic red flags — cap the total at 20

- A Singleton that is not process-wide immutable config
- A Strategy or Factory interface with one implementation
- Check-then-act on a contended resource
- An unbounded queue, or unbounded thread creation
- Domain classes importing ORM or vendor types
- A remote call with no timeout
- Retry on a non-idempotent operation, no idempotency key
- Every class name ending in Manager or Helper
- A breaker, queue or cache with no stated metric
- Writing to a database and a queue as two separate commits

## Pattern tiers

**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 + budget, Expand-contract, 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

**Doubtful** (usually a smell — needs an unusually good justification): Singleton, Prototype, Interpreter, Service Locator, Anemic Domain Model, Double-checked locking, Dual writes

## The 30 LLD / machine-coding problems

Each carries the axis of change, the patterns that legitimately fit, the plausible wrong answer, and the follow-up probe that breaks a memorised one. Starred entries are the ten near-certain to appear.

01. Parking Lot *
02. Elevator System *
03. Vending Machine *
04. Rate Limiter *
05. LRU / LFU Cache *
06. Notification System *
07. Library Management *
08. Splitwise *
09. Movie Ticket Booking *
10. Chess *
11. Logging Framework
12. ATM
13. Ride-Hailing Dispatch
14. Food Delivery
15. Cart & Checkout
16. Digital Wallet
17. Message Queue
18. URL Shortener
19. Task Scheduler
20. KV Store with TTL
21. Custom HashMap
22. Text Editor + Undo
23. Board Game Engine
24. Inventory Management
25. Hotel Booking
26. Social Media Feed
27. Chat Application
28. File System Metadata
29. Payment Gateway Layer
30. Feature Flag Service

## Frequently asked questions

### What is code-design-patterns?

code-design-patterns is a free, open-source Claude Skill for software design patterns. It is a folder of Markdown — one SKILL.md router plus eleven reference files — that Claude loads automatically when the work involves class design, refactoring, architecture or a low-level design problem. It covers 115 pattern entries, 21 anti-patterns, a 10-dimension evaluation rubric and 30 canonical LLD problems, and it is MIT licensed.

### How do I install it in Claude Code?

Clone the repo and copy one folder into your skills directory — there is no build step and no runtime dependency: 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 repo for project scope, or ~/.claude/skills/ for every project. For Claude.ai and Cowork, upload the folder under Settings → Capabilities → Skills. A packaged single-file .skill bundle is also available in the repo’s dist/ folder.

### How is this different from just asking Claude about design patterns?

Claude already knows the 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 the default. Every pattern in the output must trace to a specific, stated force in the requirements; if the force cannot be named, the pattern is removed before you see it. Its main job is subtraction, not addition.

### Which design patterns does it cover?

All 23 Gang of Four patterns — Strategy, Factory Method, Abstract Factory, Builder, Prototype, Singleton, Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy, Chain of Responsibility, Command, Interpreter, Iterator, Mediator, Memento, Observer, State, Template Method and Visitor — plus architectural patterns (dependency injection, repository, hexagonal / ports-and-adapters, CQRS, event sourcing, result types, plugin systems, feature flags), concurrency patterns (worker pool, pipeline, fan-out/fan-in, actor, single-writer, compare-and-swap, backpressure), distributed-resilience patterns (circuit breaker, retry with budget, hedged requests, bulkhead, saga, transactional outbox, idempotency key, five rate-limiting algorithms, expand-contract migration) and frontend component patterns (compound components, custom hooks, provider splitting, props getters, state reducers, error boundaries), persistence patterns (optimistic and pessimistic locking, isolation levels, write skew, unique constraints, conditional writes, aggregates as transaction boundaries, multi-tenant isolation) and API contract patterns (idempotent HTTP semantics, error contracts, pagination, compatible evolution, versioning, deprecation, webhooks). 115 entries in total, across eleven reference files.

### What are tiers, and why is Singleton in the bottom one?

Patterns are ranked by how often they are actually the right answer in production code, not by how famous they are — ★★ confident , ★ situational , · last resort . The idea is borrowed from Christopher Alexander’s A Pattern Language , the 1977 book the Gang of Four took the term “design pattern” from, which rated its 253 patterns the same way. Singleton sits in the bottom tier because in most codebases it is global mutable state with a nicer name, and passing the dependency explicitly is both simpler and testable.

### What anti-patterns does it detect?

Twenty-one code smells, each with a detectable signature and the smallest first refactoring move — including pattern-stuffing, god object, anemic domain model, primitive obsession, feature envy, shotgun surgery, leaky abstraction, singleton abuse, premature abstraction, boolean-parameter explosion, check-then-act races, and writing to a database and a queue as two separate commits. Pattern-stuffing is the one the whole skill exists to prevent.

### Does it help with LLD and machine-coding interviews?

Yes. It ships a bank of 30 canonical low-level design problems — parking lot, elevator system, vending machine, rate limiter, LRU cache, Splitwise, chess, ATM, URL shortener, message queue and more. Each entry carries the axis of change, the patterns that legitimately fit, the plausible wrong answer, and the follow-up probe that breaks a memorised one. You can use it to practise, to generate problems, or as ground truth when grading a design out of 30.

### Does it work with Cursor, Codex, or other AI coding agents?

It is built and tested for Claude — Claude Code, Claude Desktop, Claude.ai and Cowork. Because it is plain Markdown in the SKILL.md convention with zero dependencies and no runtime, any agent that reads SKILL.md folders can load it as-is; the routing front-matter is the only Claude-specific part, and it degrades to an ordinary heading elsewhere.

### Is it free?

Yes — MIT licensed, free for personal and commercial use, no account, no telemetry, no network calls. The source is on GitHub .

### How does the 10-dimension rubric work?

Before a design is shown to you, Claude scores it against ten dimensions — each 0–3, for a total out of 30 — covering requirement traceability, the named axis of change, cohesion and coupling, concurrency correctness, failure handling, testability, observability, cost, simplicity, and whether every pattern used was justified. Automatic red flags, such as a pattern with no named force or a Manager class, cap the total at 20 no matter how the rest scores.

## Links

- Website: https://codedesignpatterns.dev
- Source: https://github.com/00suryavanshi00/code-design-patterns
- Short summary: https://codedesignpatterns.dev/llms.txt
- License: MIT