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.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 25, 2025⬇️1downloads

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.
namerefactor-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:

  1. High churn AND high complexity
  2. Frequently causing bugs
  3. Blocking feature development