refactor-arch-hotspots
[Code Quality] Identifies architectural hotspots: high-churn files, coupling issues, layer violations, and dependency tangles. Use to find systemic issues that cause repeated bugs or slow development.
When & Why to Use This Skill
This Claude skill is a specialized architectural analysis tool designed to identify 'hotspots' within a codebase that contribute to technical debt and development friction. By analyzing high-churn files, coupling metrics, and layer violations, it helps engineering teams pinpoint systemic structural issues that cause recurring bugs and slow down the software development lifecycle (SDLC). It provides actionable insights for refactoring by focusing on dependency tangles and instability, ensuring a more maintainable and scalable software architecture.
Use Cases
- Identifying 'God Modules' and high-churn files that require frequent changes and indicate poor abstraction boundaries.
- Detecting architectural layer violations, such as UI components directly accessing the database or business logic leaking into controllers.
- Analyzing coupling metrics (Afferent and Efferent) to evaluate the impact of changes and identify modules that are too unstable or overly depended upon.
- Resolving dependency tangles and circular imports that complicate builds and hinder modularity.
- Prioritizing refactoring efforts by cross-referencing code complexity with change frequency to maximize ROI on technical debt reduction.
| name | refactor-arch-hotspots |
|---|---|
| description | "[Code Quality] Identifies architectural hotspots: high-churn files, coupling issues, layer violations, and dependency tangles. Use to find systemic issues that cause repeated bugs or slow development." |
Refactor: Architecture Hotspots
Find structural issues that create ongoing maintenance burden.
Hotspot Categories
1. High-Churn Files
Files changed frequently indicate poor abstraction boundaries.
2. Coupling Analysis
- Afferent Coupling (Ca): Who depends on this?
- Efferent Coupling (Ce): What does this depend on?
- Instability (I): Ce / (Ca + Ce)
3. Layer Violations
- UI accessing database directly
- Business logic in controllers
- Circular module dependencies
4. Dependency Tangles
- Import cycles
- Bidirectional dependencies
- God modules everything imports
Prioritization
Focus on hotspots that are:
- High churn AND high complexity
- Frequently causing bugs
- Blocking feature development