improve-codebase-architecture

To refactor shallow modules, you must identify tightly-coupled code lacking locality and consolidate its behavior behind clear, deep interfaces. This process transforms fragmented logic spread across multiple files into high-leverage architectural components that are significantly easier to test and maintain.

A deep module is an architectural component with a complex internal implementation hidden behind a simple, minimal interface. This design provides high leverage and maintenance locality, allowing developers to interact with complex logic without navigating tightly-coupled shallow modules.

You need to refactor tightly-coupled code when architectural friction makes it difficult to test, navigate, or maintain your software. If understanding a single feature requires jumping between five different shallow files, refactoring for modularity and interface boundaries is required.

Yes, parallel sub-agents can explore multiple architectural patterns for a single module simultaneously. This ensures the best interface design is chosen by evaluating different refactoring candidates before consolidating behavior into a deep, testable component.

Yes, improving codebase architecture requires adherence to domain-specific vocabulary defined in project context files. This ensures that refactored modules, seams, and adapter management align with existing architectural principles and business logic.