arabelatso/design-smell-detector
Identify design quality issues in code including high coupling, low cohesion, God classes, long methods, and other code smells. Use when: (1) Reviewing code architecture and design quality, (2) Identifying refactoring opportunities, (3) Detecting God classes or classes with too many responsibilities, (4) Finding high coupling or low cohesion issues, (5) Analyzing code maintainability and technical debt. Detects coupling smells, cohesion problems, complexity issues, size violations, and encapsulation problems with actionable refactoring suggestions.
npx skills add https://github.com/ArabelaTso/Skills-4-SE --skill design-smell-detectorIdentify and address design quality issues in code through automated smell detection and refactoring guidance.
# Analyze a single file
python scripts/detect_smells.py src/app.py
# Analyze entire directory
python scripts/detect_smells.py src/
# Output as JSON
python scripts/detect_smells.py src/ --format json
Found 5 design smell(s): 1 critical, 3 major, 1 minor
CRITICAL ISSUES:
🔴 src/services.py:45 - God Class
Class 'UserManager' has 25 methods (threshold: 20)
💡 Split into multiple smaller, focused classes
MAJOR ISSUES:
🟠 src/models.py:120 - Low Cohesion
Class 'Order' has low cohesion (score: 0.25)
💡 Group related methods/attributes or split class
🟠 src/utils.py:89 - Long Method
Method 'process_order' has 67 lines (threshold: 50)
💡 Extract smaller methods or refactor
High Coupling: Too many dependencies
Feature Envy: Method uses other class more than own
Inappropriate Intimacy: Classes too tightly coupled
Low Cohesion: Class members unrelated
God Class: Class knows/does too much
High Cyclomatic Complexity: Too many decision points
Long Method: Method too long
Long Parameter List: Too many parameters
Large Module: Module too large
Data Class: Only data, no behavior
Exposed Internal State: Implementation details exposed
Analyze codebase for design smells:
python scripts/detect_smells.py src/
Examine detected smells by severity:
Focus on:
Use refactoring strategies based on smell type.
See refactoring_strategies.md for detailed solutions.
Re-run detection to measure progress:
python scripts/detect_smells.py src/
Compare metrics before/after.
Symptoms:
Example:
# ❌ God Class
class Application:
# 30+ methods handling:
# - User management
# - Order processing
# - Payment handling
# - Reporting
# - Email notifications
# - File operations
pass
Refactoring:
# ✅ Split by responsibility
class UserManager:
pass
class OrderProcessor:
pass
class PaymentHandler:
pass
class ReportGenerator:
pass
Symptoms:
Example:
# ❌ High coupling
class UserService:
def __init__(self):
self.db = Database()
self.cache = Cache()
self.logger = Logger()
self.validator = Validator()
self.email = EmailService()
self.sms = SMSService()
# ... many more
Refactoring:
# ✅ Dependency injection
class UserService:
def __init__(self, db, logger, notifier):
self.db = db
self.logger = logger
self.notifier = notifier # Abstraction
Symptoms:
Example:
# ❌ Low cohesion
class UserManager:
def create_user(self):
pass
def send_email(self):
pass
def log_activity(self):
pass
def calculate_discount(self):
pass
Refactoring:
# ✅ High cohesion - focused classes
class UserRepository:
def create_user(self):
pass
class EmailService:
def send_email(self):
pass
class ActivityLogger:
def log_activity(self):
pass
Symptoms:
Example:
# ❌ Long method (100+ lines)
def process_order(order):
# Validate (20 lines)
# Calculate price (15 lines)
# Save to DB (10 lines)
# Send email (20 lines)
# Update stats (10 lines)
# Log activity (15 lines)
pass
Refactoring:
# ✅ Extract methods
def process_order(order):
validate_order(order)
total = calculate_total(order)
save_order(order, total)
send_confirmation(order)
update_statistics()
log_activity(order)
Dependency Injection:
# Inject dependencies instead of creating them
class OrderService:
def __init__(self, db, logger):
self.db = db
self.logger = logger
Interface Abstraction:
# Depend on abstractions, not implementations
from abc import ABC, abstractmethod
class PaymentGateway(ABC):
@abstractmethod
def charge(self, amount):
pass
class PaymentProcessor:
def __init__(self, gateway: PaymentGateway):
self.gateway = gateway
Extract Class:
# Split into focused classes
class User:
# User data and behavior
class UserRepository:
# Database operations
class EmailService:
# Email operations
Move Method:
# Move method to appropriate class
class Account:
def get_formatted_balance(self): # Moved from reporter
return f"${self.balance:.2f}"
Extract Method:
# Break complex method into smaller ones
def process_order(order):
validate_order(order)
calculate_total(order)
save_order(order)
Replace Conditional with Polymorphism:
# Use inheritance instead of conditionals
class Customer:
def calculate_price(self, base_price):
return base_price
class PremiumCustomer(Customer):
def calculate_price(self, base_price):
return base_price * 0.9
For comprehensive refactoring strategies, see refactoring_strategies.md.
| Smell | Metric | Threshold |
|-------|--------|-----------|
| God Class | Methods | > 20 |
| God Class | Attributes | > 15 |
| God Class | LOC | > 500 |
| High Coupling | Imports | > 20 |
| Low Cohesion | LCOM | > 0.7 |
| Long Method | LOC | > 50 |
| High Complexity | Cyclomatic | > 10 |
| Long Parameter List | Parameters | > 5 |
LCOM (Lack of Cohesion of Methods):
Cyclomatic Complexity:
Fan-out (Coupling):
For complete descriptions, examples, and solutions for all design smells, see smell_catalog.md.
Includes:
Integrate into workflow:
# Pre-commit hook
python scripts/detect_smells.py src/
# CI/CD pipeline
make check-design-smells
Monitor trends:
Sprint 1: 15 God classes, 45 long methods
Sprint 2: 12 God classes, 38 long methods
Sprint 3: 8 God classes, 25 long methods
Focus on:
Before/after metrics:
Before: LCOM = 0.85 (low cohesion)
After: LCOM = 0.25 (high cohesion)
Goal: Identify technical debt in legacy system
Approach:
Goal: Automated design quality checks in PR reviews
Approach:
Goal: Evaluate system architecture quality
Approach:
#!/bin/bash
# .git/hooks/pre-commit
python scripts/detect_smells.py src/
if [ $? -ne 0 ]; then
echo "Critical design smells detected. Commit aborted."
exit 1
fi
# .github/workflows/quality.yml
name: Design Quality Check
on: [push, pull_request]
jobs:
check-smells:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Detect design smells
run: python scripts/detect_smells.py src/
- name: Upload report
uses: actions/upload-artifact@v3
with:
name: smell-report
path: smell-report.json
Most IDEs support similar analysis through plugins:
Problem: Legitimate design flagged as smell
Solution:
Problem: Too many smells to address
Solution:
Problem: Tests fail after refactoring
Solution:
See smell_catalog.md for:
See refactoring_strategies.md for:
Take arabelatso/design-smell-detector from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.