interface-pollution

Detect and avoid unnecessary interface abstractions

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025

When & Why to Use This Skill

This Claude skill specializes in identifying and mitigating 'interface pollution'—the practice of creating unnecessary abstractions before they are truly required. By analyzing code patterns, it helps developers adhere to clean architecture principles, ensuring interfaces are defined at the point of consumption rather than production. This leads to reduced technical debt, improved code maintainability, and a more decoupled codebase by providing actionable refactoring strategies and detection checklists.

Use Cases

  • Automated Code Reviews: Scanning pull requests to identify interfaces that are prematurely defined in the same package as their implementations.
  • Refactoring Monolithic Interfaces: Detecting 'fat' interfaces with excessive methods and providing guidance on splitting them into smaller, purpose-driven abstractions.
  • Architectural Auditing: Identifying 'one-to-one' interface-to-implementation mappings that add unnecessary boilerplate without providing polymorphic value.
  • Design Pattern Enforcement: Assisting developers during the design phase to ensure new code follows the 'Consumer-Defined Interfaces' pattern to maintain loose coupling.
nameinterface-pollution
descriptionDetect and avoid unnecessary interface abstractions

Interface Pollution Detection

Interface pollution occurs when interfaces are created before they're needed. Define interfaces at consumption point, not production.

Pollution Patterns

WRONG - Producer defines interface prematurely

// In package "storage"
type UserRepository interface {
    GetUser(id int) (*User, error)
    SaveUser(u *User) error
}

type PostgresRepo struct{}

func (p *PostgresRepo) GetUser(id int) (*User, error) { ... }
func (p *PostgresRepo) SaveUser(u *User) error { ... }

CORRECT - Consumer defines minimal interface

// In package "handler"
type UserGetter interface {
    GetUser(id int) (*User, error)
}

func HandleRequest(repo UserGetter) http.Handler {
    // Only needs GetUser, not entire repository
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        user, _ := repo.GetUser(123)
        // ...
    })
}

// Concrete type lives in storage package
// Handler depends on small interface, not full implementation

Detection Checklist

You have interface pollution if:

  • Interface defined in same package as implementation
  • Only one implementation exists
  • Interface has >5 methods
  • Name ends in "Interface" or "Impl"

Refactoring Strategy

Before:

type DataService interface {
    Read() error
    Write() error
    Validate() error
    Transform() error
}

After:

// Split by actual usage
type Reader interface { Read() error }
type Writer interface { Write() error }

// Compose where needed
type ReadWriter interface {
    Reader
    Writer
}