design-patterns

Detect, suggest, and evaluate GoF design patterns in TypeScript/JavaScript codebases. Use when refactoring code, applying singleton/factory/observer/strategy patterns, reviewing pattern quality, or finding stack-native alternatives for React, Angular, NestJS, and Vue.

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./examples/skills/design-patterns/SKILL.md

Design Patterns Analyzer Skill

Purpose: Detect, suggest, and evaluate Gang of Four (GoF) design patterns in TypeScript/JavaScript codebases with stack-aware adaptations.

Core Capabilities

Stack Detection: Identify primary framework/library (React, Angular, NestJS, Vue, Express, RxJS, Redux, ORMs)
Pattern Detection: Find existing implementations of 23 GoF patterns
Smart Suggestions: Recommend patterns to fix code smells, using stack-native idioms when available
Quality Evaluation: Assess pattern implementation quality against best practices

Operating Modes

Mode 1: Detection

Trigger: User requests pattern detection or analysis Output: JSON report of patterns found with confidence scores and stack context

Workflow:

1. Stack Detection (package.json, tsconfig.json, framework files)
2. Pattern Search (Glob for candidates -> Grep for signatures -> Read for validation)
3. Classification (native to stack vs custom implementations)
4. Confidence Scoring (0.0-1.0 based on detection rules)
5. JSON Report Generation

Example invocation:

/design-patterns detect src/
/design-patterns analyze --format=json

Mode 2: Suggestion

Trigger: User requests pattern suggestions or refactoring advice Output: Markdown report with prioritized suggestions and stack-adapted examples

Workflow:

1. Code Smell Detection (switch statements, long parameter lists, global state, etc.)
2. Pattern Matching (map smell -> applicable patterns)
3. Stack Adaptation (prefer native framework patterns over custom implementations)
4. Priority Ranking (impact x feasibility)
5. Markdown Report with Code Examples

Example invocation:

/design-patterns suggest src/payment/
/design-patterns refactor --focus=creational

Mode 3: Evaluation

Trigger: User requests pattern quality assessment Output: JSON report with scores per evaluation criterion

Workflow:

1. Pattern Identification (which pattern is implemented)
2. Criteria Assessment (correctness, testability, SOLID compliance, documentation)
3. Issue Detection (common mistakes, anti-patterns)
4. Scoring (0-10 per criterion)
5. JSON Report with Recommendations

Example invocation:

/design-patterns evaluate src/services/singleton.ts
/design-patterns quality --pattern=observer

Methodology

Phase 1: Stack Detection

Sources (in priority order):

package.json -> Check dependencies and devDependencies
Framework-specific files -> angular.json, next.config.*, nest-cli.json, vite.config.*
tsconfig.json -> Check compilerOptions, paths, lib
File extensions -> *.jsx, *.tsx, *.vue presence

Detection Rules (from signatures/stack-patterns.yaml):

React: react in deps + *.jsx/*.tsx files
Angular: @angular/core + angular.json
NestJS: @nestjs/core + nest-cli.json
Vue: vue v3+ + *.vue files
Express: express in deps + app.use patterns
RxJS: rxjs in deps + Observable usage
Redux/Zustand: redux/zustand in deps + store patterns
Prisma/TypeORM: prisma/typeorm in deps + schema files

Output:

{
  "stack_detected": {
    "primary": "react",
    "version": "18.2.0",
    "secondary": ["typescript", "zustand", "prisma"],
    "detection_sources": ["package.json", "tsconfig.json", "37 *.tsx files"],
    "confidence": 0.95
  }
}

Phase 2: Pattern Detection

Search Strategy:

Glob Phase: Find candidate files by naming convention
- *Singleton*.ts, *Factory*.ts, *Strategy*.ts, *Observer*.ts, etc.
- *Manager*.ts, *Builder*.ts, *Adapter*.ts, *Proxy*.ts, etc.
Grep Phase: Search for pattern signatures (from signatures/detection-rules.yaml)
- Primary signals: private constructor, static getInstance(), subscribe(), createXxx(), etc.
- Secondary signals: Interface naming, delegation patterns, method signatures
Read Phase: Validate pattern structure
- Parse class/interface definitions
- Verify relationships (inheritance, composition, delegation)
- Check for complete pattern implementation vs partial usage

Confidence Scoring:

0.9-1.0: All primary + secondary signals present, structure matches exactly
0.7-0.89: All primary signals + some secondary, minor deviations
0.5-0.69: Primary signals present, missing secondary validation
0.3-0.49: Naming convention matches, weak structural evidence
0.0-0.29: Insufficient evidence, likely false positive

Classification:

native: Pattern implemented using stack-native features (React Context, Angular Services, NestJS Guards, etc.)
custom: Manual TypeScript implementation
library: Third-party library providing pattern (RxJS Subject, Redux Store, etc.)

Phase 3: Code Smell Detection

Target Smells (from signatures/code-smells.yaml):

Switch on Type -> Strategy/Factory pattern
Long Parameter List (>4) -> Builder pattern
Global State Access -> Singleton (or preferably DI)
Duplicated Conditionals on State -> State pattern
Scattered Notification Logic -> Observer pattern
Complex Object Creation -> Factory/Abstract Factory
Tight Coupling to Concrete Classes -> Adapter/Bridge
Repetitive Interface Conversions -> Adapter pattern
Deep Nesting for Feature Addition -> Decorator pattern
Large Class with Many Responsibilities -> Facade pattern

Detection Heuristics:

Grep for switch (.*type), switch (.*kind), switch (.*mode)
Count function parameters: function \w+\([^)]{60,}\) (approximation for >4 params)
Search for global access: window\., global\., process\.env\.\w+ (not in config files)
Find state conditionals: if.*state.*===.*&&.*if.*state.*===
Find notification patterns: forEach.*notify, map.*\.emit\(

Phase 4: Stack-Aware Suggestions

Adaptation Logic (from signatures/stack-patterns.yaml):

IF pattern_detected == "custom" AND stack_has_native_equivalent:
  SUGGEST: "Use stack-native pattern instead"
  PROVIDE: Side-by-side comparison (current vs recommended)

ELSE IF code_smell_detected AND pattern_missing:
  IF stack_provides_pattern:
    SUGGEST: Stack-native implementation with examples
  ELSE:
    SUGGEST: Custom TypeScript implementation with best practices

ELSE IF pattern_implemented_incorrectly:
  PROVIDE: Refactoring steps to fix anti-patterns

Example Adaptations:

Pattern	Stack	Native Alternative	Recommendation
Singleton	React	Context API + Provider	Use `createContext()` instead of `getInstance()`
Observer	Angular	RxJS Subject/BehaviorSubject	Use built-in Observables, not custom implementation
Decorator	NestJS	@Injectable() decorators + Interceptors	Use framework interceptors
Strategy	Vue 3	Composition API composables	Use `ref()` + composables instead of classes
Chain of Responsibility	Express	Middleware (`app.use()`)	Use Express middleware chain
Command	Redux	Action creators + reducers	Use Redux actions, not custom command objects

Phase 5: Quality Evaluation

Criteria (from checklists/pattern-evaluation.md):

Correctness (0-10): Does it match the canonical pattern structure?
Testability (0-10): Can dependencies be mocked/stubbed easily?
Single Responsibility (0-10): Does it do one thing only?
Open/Closed Principle (0-10): Extensible without modification?
Documentation (0-10): Clear intent, descriptive naming?

Scoring Guidelines:

9-10: Exemplary, reference-quality implementation
7-8: Good, minor improvements possible
5-6: Acceptable, notable issues to address
3-4: Problematic, significant refactoring needed
0-2: Incorrect or severely flawed

Issue Detection:

Hard-coded dependencies (Singleton with new inside getInstance)
God classes (too many responsibilities)
Leaky abstractions (exposing internal structure)
Missing error handling
Poor naming (Strategy1, Strategy2 instead of descriptive names)

Output Formats

Detection Mode (JSON)

{
  "metadata": {
    "scan_date": "2026-01-21T10:30:00Z",
    "scope": "src/",
    "files_scanned": 147,
    "execution_time_ms": 2341
  },
  "stack_detected": {
    "primary": "react",
    "version": "18.2.0",
    "secondary": ["typescript", "zustand", "prisma"],
    "detection_sources": ["package.json", "tsconfig.json", "37 *.tsx files"],
    "confidence": 0.95
  },
  "patterns_found": {
    "singleton": [
      {
        "file": "src/lib/api-client.ts",
        "lines": "5-28",
        "confidence": 0.85,
        "type": "custom",
        "signals": ["private constructor", "static getInstance", "private static instance"],
        "note": "Consider using React Context instead for better testability"
      }
    ],
    "observer": [
      {
        "file": "src/hooks/useAuth.ts",
        "lines": "12-45",
        "confidence": 0.92,
        "type": "native",
        "implementation": "React useState + useEffect",
        "note": "Correctly using React's built-in observer pattern"
      }
    ],
    "factory": [
      {
        "file": "src/services/notification-factory.ts",
        "lines": "8-67",
        "confidence": 0.78,
        "type": "custom",
        "signals": ["createNotification method", "type discrimination", "returns interface"]
      }
    ]
  },
  "summary": {
    "total_patterns": 7,
    "native_to_stack": 4,
    "custom_implementations": 3,
    "by_category": {
      "creational": 2,
      "structural": 3,
      "behavioral": 2
    },
    "by_confidence": {
      "high": 5,
      "medium": 2,
      "low": 0
    }
  },
  "recommendations": [
    "Consider replacing custom Singleton (api-client.ts) with React Context for better DI",
    "Review Factory pattern (notification-factory.ts) - could be simplified with strategy pattern"
  ]
}

Suggestion Mode (Markdown)

# Design Pattern Suggestions

**Scope**: `src/payment/`
**Stack**: React 18 + TypeScript + Stripe
**Date**: 2026-01-21

---

## High Priority

### 1. Strategy Pattern: `src/payment/processor.ts:45-89`

**Code Smell**: Switch statement on payment type (4 cases, 78 lines)

**Current Implementation** (lines 52-87):
```typescript
switch (paymentType) {
  case 'credit':
    // 20 lines of credit card logic
    break;
  case 'paypal':
    // 15 lines of PayPal logic
    break;
  case 'crypto':
    // 18 lines of crypto logic
    break;
  case 'bank':
    // 12 lines of bank transfer logic
    break;
}

Recommended (React-adapted Strategy):

// Define strategy interface
interface PaymentStrategy {
  process: (amount: number) => Promise<PaymentResult>;
}

// Custom hooks as strategies
const useCreditPayment = (): PaymentStrategy => ({
  process: async (amount) => { /* credit logic */ }
});

const usePaypalPayment = (): PaymentStrategy => ({
  process: async (amount) => { /* PayPal logic */ }
});

// Strategy selection hook
const usePaymentStrategy = (type: PaymentType): PaymentStrategy => {
  const strategies = {
    credit: useCreditPayment(),
    paypal: usePaypalPayment(),
    crypto: useCryptoPayment(),
    bank: useBankPayment(),
  };
  return strategies[type];
};

// Usage in component
const PaymentForm = ({ type }: Props) => {
  const strategy = usePaymentStrategy(type);
  const handlePay = () => strategy.process(amount);
  // ...
};

Impact:

Complexity: Reduces cyclomatic complexity from 12 to 2
Extensibility: New payment methods = new hook, no modification to existing code
Testability: Each strategy hook can be tested in isolation
Effort: ~2 hours (extract logic into hooks, add tests)

Medium Priority

2. Observer Pattern: `src/cart/CartManager.ts:23-156`

Code Smell: Manual notification logic scattered across 8 methods

Current: Manual loops calling update functions Recommended: Use Zustand store (already in dependencies)

// Instead of custom observer:
import create from 'zustand';

interface CartStore {
  items: CartItem[];
  addItem: (item: CartItem) => void;
  removeItem: (id: string) => void;
  // Zustand automatically notifies subscribers
}

export const useCartStore = create<CartStore>((set) => ({
  items: [],
  addItem: (item) => set((state) => ({ items: [...state.items, item] })),
  removeItem: (id) => set((state) => ({ items: state.items.filter(i => i.id !== id) })),
}));

// Components auto-subscribe:
const CartDisplay = () => {
  const items = useCartStore((state) => state.items);
  // Re-renders automatically on cart changes
};

Impact:

LOC: Reduces from 156 to ~25 lines
Stack-native: Uses existing Zustand dependency
Testability: Zustand stores are easily tested
Effort: ~1.5 hours

Summary

Total suggestions: 4
High priority: 2 (Strategy, Observer)
Medium priority: 2 (Builder, Facade)
Estimated total effort: ~6 hours
Primary benefits: Reduced complexity, improved testability, stack-native idioms

### Evaluation Mode (JSON)

```json
{
  "file": "src/services/config-singleton.ts",
  "pattern": "singleton",
  "lines": "5-34",
  "scores": {
    "correctness": 8,
    "testability": 4,
    "single_responsibility": 9,
    "open_closed": 7,
    "documentation": 6,
    "overall": 6.8
  },
  "details": {
    "correctness": {
      "score": 8,
      "rationale": "Implements singleton structure correctly with private constructor and static getInstance",
      "issues": ["Missing thread-safety consideration (not critical in JS single-threaded context)"]
    },
    "testability": {
      "score": 4,
      "rationale": "Hard to mock or reset instance in tests",
      "issues": [
        "No reset method for test isolation",
        "Static instance makes dependency injection impossible",
        "Tests must run in specific order or share state"
      ],
      "suggestions": [
        "Add resetInstance() method for tests (with appropriate guards)",
        "Consider using dependency injection instead"
      ]
    },
    "single_responsibility": {
      "score": 9,
      "rationale": "Focuses solely on configuration management",
      "issues": []
    },
    "open_closed": {
      "score": 7,
      "rationale": "Configuration can be extended but requires modification for new sources",
      "suggestions": ["Consider strategy pattern for configuration sources"]
    },
    "documentation": {
      "score": 6,
      "rationale": "Has JSDoc but missing rationale for singleton choice",
      "suggestions": ["Document why singleton is chosen over DI", "Add usage examples"]
    }
  },
  "recommendations": [
    {
      "priority": "high",
      "suggestion": "Add test-friendly reset mechanism or refactor to use DI",
      "rationale": "Current implementation makes testing difficult"
    },
    {
      "priority": "medium",
      "suggestion": "Document singleton rationale in JSDoc",
      "rationale": "Team members should understand why global state is necessary here"
    }
  ]
}

Constraints & Guidelines

Read-Only Analysis

No modifications: This skill only analyzes and suggests, never modifies code
No file creation: Does not generate refactored code files
User decision: All suggestions require explicit user approval before implementation

Language Focus

Primary: TypeScript (.ts, .tsx)
Secondary: JavaScript (.js, .jsx)
Exclusions: Other languages (Python, Java, C#) not supported

Pattern Coverage

Creational (5): Singleton, Factory Method, Abstract Factory, Builder, Prototype
Structural (7): Adapter, Bridge, Composite, Decorator, Facade, Flyweight, Proxy
Behavioral (11): Chain of Responsibility, Command, Iterator, Mediator, Memento, Observer, State, Strategy, Template Method, Visitor, Interpreter

Performance Considerations

Large codebases (>500 files): Use --scope to limit scan to specific directories
Parallel search: Grep searches run independently for each pattern
Caching: Stack detection results cached per session to avoid redundant package.json reads

Usage Examples

Basic Detection

# Detect all patterns in src/
/design-patterns detect src/

# Detect only creational patterns
/design-patterns detect src/ --category=creational

# Focus on specific pattern
/design-patterns detect src/ --pattern=singleton

Targeted Suggestions

# Get suggestions for payment module
/design-patterns suggest src/payment/

# Focus on specific smell
/design-patterns suggest src/ --smell=switch-on-type

# High priority only
/design-patterns suggest src/ --priority=high

Quality Evaluation

# Evaluate specific file
/design-patterns evaluate src/services/api-client.ts

# Evaluate all singletons
/design-patterns evaluate src/ --pattern=singleton

# Full quality report
/design-patterns evaluate src/ --detailed

Integration with Other Skills

This skill can be inherited by:

refactoring-specialist.md: Provides pattern knowledge for refactoring
code-reviewer.md: Adds pattern detection to review process
architecture-advisor.md: Informs architectural decisions with pattern usage

Reference Files

reference/patterns-index.yaml: Machine-readable index of 23 patterns with metadata
reference/creational.md: Creational patterns documentation
reference/structural.md: Structural patterns documentation
reference/behavioral.md: Behavioral patterns documentation
signatures/detection-rules.yaml: Regex patterns and heuristics for detection
signatures/code-smells.yaml: Mapping from code smells to applicable patterns
signatures/stack-patterns.yaml: Stack detection rules and native pattern equivalents
checklists/pattern-evaluation.md: Quality evaluation criteria and scoring guidelines

Version

Skill Version: 1.0.0 Pattern Coverage: 23 GoF patterns Supported Stacks: 8 (React, Angular, NestJS, Vue, Express, RxJS, Redux/Zustand, ORMs) Last Updated: 2026-01-21

Repository: FlorianBruniaux/claude-code-ultimate-guide
Path: examples/skills/design-patterns/SKILL.md
Commit: 752edfe

Last updated: about 9 hours ago
First committed: 7 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

design-patterns

Design Patterns Analyzer Skill

Core Capabilities

Operating Modes

Mode 1: Detection

Mode 2: Suggestion

Mode 3: Evaluation

Methodology

Phase 1: Stack Detection

Phase 2: Pattern Detection

Phase 3: Code Smell Detection

Phase 4: Stack-Aware Suggestions

Phase 5: Quality Evaluation

Output Formats

Detection Mode (JSON)

Suggestion Mode (Markdown)

Medium Priority

2. Observer Pattern: src/cart/CartManager.ts:23-156

Summary

Constraints & Guidelines

Read-Only Analysis

Language Focus

Pattern Coverage

Performance Considerations

Usage Examples

Basic Detection

Targeted Suggestions

Quality Evaluation

Integration with Other Skills

Reference Files

Version

Is this your skill?

2. Observer Pattern: `src/cart/CartManager.ts:23-156`