interface-pollution
Detect and avoid unnecessary interface abstractions
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.
| name | interface-pollution |
|---|---|
| description | Detect 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
}