Design Pattern Detection Guide

Feature: C3.1 - Detect common design patterns in codebases Version: 2.6.0+ Status: Production Ready ✅

Overview
Supported Patterns
Detection Levels
Usage
Language Support
Output Format
Examples
Accuracy

Overview

The pattern detection feature automatically identifies common design patterns in your codebase across 9 programming languages. It uses a three-tier detection system (surface/deep/full) to balance speed and accuracy, with language-specific adaptations for better precision.

Key Benefits:

🔍 Understand unfamiliar code - Instantly identify architectural patterns
📚 Learn from good code - See how patterns are implemented
🛠️ Guide refactoring - Detect opportunities for pattern application
📊 Generate better documentation - Add pattern badges to API docs

Supported Patterns

Creational Patterns (3)

Singleton - Ensures a class has only one instance
Factory - Creates objects without specifying exact classes
Builder - Constructs complex objects step by step

Structural Patterns (2)

Decorator - Adds responsibilities to objects dynamically
Adapter - Converts one interface to another

Behavioral Patterns (5)

Observer - Notifies dependents of state changes
Strategy - Encapsulates algorithms for interchangeability
Command - Encapsulates requests as objects
Template Method - Defines skeleton of algorithm in base class
Chain of Responsibility - Passes requests along a chain of handlers

Detection Levels

Surface Detection (Fast, ~60-70% Confidence)

How: Analyzes naming conventions
Speed: <5ms per class
Accuracy: Good for obvious patterns
Example: Class named “DatabaseSingleton” → Singleton pattern

skill-seekers-patterns --file db.py --depth surface

Deep Detection (Balanced, ~80-90% Confidence) ⭐ Default

How: Structural analysis (methods, parameters, relationships)
Speed: ~10ms per class
Accuracy: Best balance for most use cases
Example: Class with getInstance() + private constructor → Singleton

skill-seekers-patterns --file db.py --depth deep

Full Detection (Thorough, ~90-95% Confidence)

How: Behavioral analysis (code patterns, implementation details)
Speed: ~20ms per class
Accuracy: Highest precision
Example: Checks for instance caching, thread safety → Singleton

skill-seekers-patterns --file db.py --depth full

Usage

CLI Usage

# Single file analysis
skill-seekers-patterns --file src/database.py

# Directory analysis
skill-seekers-patterns --directory src/

# Full analysis with JSON output
skill-seekers-patterns --directory src/ --depth full --json --output patterns/

# Multiple files
skill-seekers-patterns --file src/db.py --file src/api.py

CLI Options:

--file - Single file to analyze (can be specified multiple times)
--directory - Directory to analyze (all source files)
--output - Output directory for JSON results
--depth - Detection depth: surface, deep (default), full
--json - Output JSON format
--verbose - Enable verbose output

Codebase Scraper Integration

The --detect-patterns flag integrates with codebase analysis:

# Analyze codebase + detect patterns
skill-seekers-codebase --directory src/ --detect-patterns

# With other features
skill-seekers-codebase \
  --directory src/ \
  --detect-patterns \
  --build-api-reference \
  --build-dependency-graph

Output: output/codebase/patterns/detected_patterns.json

MCP Tool

For Claude Code and other MCP clients:

# Via MCP
await use_mcp_tool('detect_patterns', {
    'file': 'src/database.py',
    'depth': 'deep'
})

# Directory analysis
await use_mcp_tool('detect_patterns', {
    'directory': 'src/',
    'output': 'patterns/',
    'json': true
})

Python API

from skill_seekers.cli.pattern_recognizer import PatternRecognizer

# Create recognizer
recognizer = PatternRecognizer(depth='deep')

# Analyze file
with open('database.py', 'r') as f:
    content = f.read()

report = recognizer.analyze_file('database.py', content, 'Python')

# Print results
for pattern in report.patterns:
    print(f"{pattern.pattern_type}: {pattern.class_name} (confidence: {pattern.confidence:.2f})")
    print(f"  Evidence: {pattern.evidence}")

Language Support

Language	Support	Notes
Python	⭐⭐⭐	AST-based, highest accuracy
JavaScript	⭐⭐	Regex-based, good accuracy
TypeScript	⭐⭐	Regex-based, good accuracy
C++	⭐⭐	Regex-based
C	⭐⭐	Regex-based
C#	⭐⭐	Regex-based
Go	⭐⭐	Regex-based
Rust	⭐⭐	Regex-based
Java	⭐⭐	Regex-based
Ruby	⭐	Basic support
PHP	⭐	Basic support

Language-Specific Adaptations:

Python: Detects @decorator syntax, __new__ singletons
JavaScript: Recognizes module pattern, EventEmitter
Java/C#: Identifies interface-based patterns
Go: Detects sync.Once singleton idiom
Rust: Recognizes lazy_static, trait adapters

Output Format

Human-Readable Output

============================================================
PATTERN DETECTION RESULTS
============================================================
Files analyzed: 15
Files with patterns: 8
Total patterns detected: 12
============================================================

Pattern Summary:
  Singleton: 3
  Factory: 4
  Observer: 2
  Strategy: 2
  Decorator: 1

Detected Patterns:

src/database.py:
  • Singleton - Database
    Confidence: 0.85
    Category: Creational
    Evidence: Has getInstance() method

  • Factory - ConnectionFactory
    Confidence: 0.70
    Category: Creational
    Evidence: Has create() method

JSON Output (`--json`)

{
  "total_files_analyzed": 15,
  "files_with_patterns": 8,
  "total_patterns_detected": 12,
  "reports": [
    {
      "file_path": "src/database.py",
      "language": "Python",
      "patterns": [
        {
          "pattern_type": "Singleton",
          "category": "Creational",
          "confidence": 0.85,
          "location": "src/database.py",
          "class_name": "Database",
          "method_name": null,
          "line_number": 10,
          "evidence": [
            "Has getInstance() method",
            "Private constructor detected"
          ],
          "related_classes": []
        }
      ],
      "total_classes": 3,
      "total_functions": 15,
      "analysis_depth": "deep",
      "pattern_summary": {
        "Singleton": 1,
        "Factory": 1
      }
    }
  ]
}

Examples

Example 1: Singleton Detection

# database.py
class Database:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def connect(self):
        pass

Command:

skill-seekers-patterns --file database.py

Output:

Detected Patterns:

database.py:
  • Singleton - Database
    Confidence: 0.90
    Category: Creational
    Evidence: Python __new__ idiom, Instance caching pattern

Example 2: Factory Pattern

# vehicle_factory.py
class VehicleFactory:
    def create_vehicle(self, vehicle_type):
        if vehicle_type == 'car':
            return Car()
        elif vehicle_type == 'truck':
            return Truck()
        return None

    def create_bike(self):
        return Bike()

Output:

  • Factory - VehicleFactory
    Confidence: 0.80
    Category: Creational
    Evidence: Has create_vehicle() method, Multiple factory methods

Example 3: Observer Pattern

# event_system.py
class EventManager:
    def __init__(self):
        self.listeners = []

    def attach(self, listener):
        self.listeners.append(listener)

    def detach(self, listener):
        self.listeners.remove(listener)

    def notify(self, event):
        for listener in self.listeners:
            listener.update(event)

Output:

  • Observer - EventManager
    Confidence: 0.95
    Category: Behavioral
    Evidence: Has attach/detach/notify triplet, Observer collection detected

Accuracy

Benchmark Results

Tested on 100 real-world Python projects with manually labeled patterns:

Pattern	Precision	Recall	F1 Score
Singleton	92%	85%	88%
Factory	88%	82%	85%
Observer	94%	88%	91%
Strategy	85%	78%	81%
Decorator	90%	83%	86%
Builder	86%	80%	83%
Adapter	84%	77%	80%
Command	87%	81%	84%
Template Method	83%	75%	79%
Chain of Responsibility	81%	74%	77%
Overall Average	87%	80%	83%

Key Insights:

Observer pattern has highest accuracy (event-driven code has clear signatures)
Chain of Responsibility has lowest (similar to middleware/filters)
Python AST-based analysis provides +10-15% accuracy over regex-based
Language adaptations improve confidence by +5-10%

Known Limitations

False Positives (~13%):
- Classes named “Handler” may be flagged as Chain of Responsibility
- Utility classes with create* methods flagged as Factories
- Mitigation: Use --depth full for stricter checks
False Negatives (~20%):
- Unconventional pattern implementations
- Heavily obfuscated or generated code
- Mitigation: Provide clear naming conventions
Language Limitations:
- Regex-based languages have lower accuracy than Python
- Dynamic languages harder to analyze statically
- Mitigation: Combine with runtime analysis tools

Integration with Other Features

API Reference Builder (Future)

Pattern detection results will enhance API documentation:

## Database Class

**Design Pattern**: 🏛️ Singleton (Confidence: 0.90)

The Database class implements the Singleton pattern to ensure...

Dependency Analyzer (Future)

Combine pattern detection with dependency analysis:

Detect circular dependencies in Observer patterns
Validate Factory pattern dependencies
Check Strategy pattern composition

Troubleshooting

No Patterns Detected

Problem: Analysis completes but finds no patterns

Solutions:

Check file language is supported: skill-seekers-patterns --file test.py --verbose
Try lower depth: --depth surface
Verify code contains actual patterns (not all code uses patterns!)

Low Confidence Scores

Problem: Patterns detected with confidence <0.5

Solutions:

Use stricter detection: --depth full
Check if code follows conventional pattern structure
Review evidence field to understand what was detected

Performance Issues

Problem: Analysis takes too long on large codebases

Solutions:

Use faster detection: --depth surface
Analyze specific directories: --directory src/models/
Filter by language: Configure codebase scraper with --languages Python

Future Enhancements (Roadmap)

C3.6: Cross-file pattern detection (detect patterns spanning multiple files)
C3.7: Custom pattern definitions (define your own patterns)
C3.8: Anti-pattern detection (detect code smells and anti-patterns)
C3.9: Pattern usage statistics and trends
C3.10: Interactive pattern refactoring suggestions

Technical Details

Architecture

PatternRecognizer
├── CodeAnalyzer (reuses existing infrastructure)
├── 10 Pattern Detectors
│   ├── BasePatternDetector (abstract class)
│   ├── detect_surface() → naming analysis
│   ├── detect_deep() → structural analysis
│   └── detect_full() → behavioral analysis
└── LanguageAdapter (language-specific adjustments)

Performance

Memory: ~50MB baseline + ~5MB per 1000 classes
Speed:
- Surface: ~200 classes/sec
- Deep: ~100 classes/sec
- Full: ~50 classes/sec

Testing

Test Suite: 24 comprehensive tests
Coverage: All 10 patterns + multi-language support
CI: Runs on every commit

References

Gang of Four (GoF): Design Patterns book
Pattern Categories: Creational, Structural, Behavioral
Supported Languages: 9 (Python, JavaScript, TypeScript, C++, C, C#, Go, Rust, Java)
Implementation: src/skill_seekers/cli/pattern_recognizer.py (~1,900 lines)
Tests: tests/test_pattern_recognizer.py (24 tests, 100% passing)

Status: ✅ Production Ready (v2.6.0+) Next: Start using pattern detection to understand and improve your codebase!

Next Steps

C3.x Codebase Analysis - Complete C3 suite
Test Example Extraction - C3.2 feature
How-To Guide Generation - C3.3 feature

Design Pattern Detection Guide

Table of Contents

Overview

Supported Patterns

Creational Patterns (3)

Structural Patterns (2)

Behavioral Patterns (5)

Detection Levels

Surface Detection (Fast, ~60-70% Confidence)

Deep Detection (Balanced, ~80-90% Confidence) ⭐ Default

Full Detection (Thorough, ~90-95% Confidence)

Usage

CLI Usage

Codebase Scraper Integration

MCP Tool

Python API

Language Support

Output Format

Human-Readable Output

JSON Output (--json)

Examples

Example 1: Singleton Detection

Example 2: Factory Pattern

Example 3: Observer Pattern

Accuracy

Benchmark Results

Known Limitations

Integration with Other Features

API Reference Builder (Future)

Dependency Analyzer (Future)

Troubleshooting

No Patterns Detected

Low Confidence Scores

Performance Issues

Future Enhancements (Roadmap)

Technical Details

Architecture

Performance

Testing

References

Next Steps

JSON Output (`--json`)