improve-codebase-architecture

To improve codebase architecture, you refactor shallow modules by identifying tightly coupled seams and deepening them into boundary interfaces. This shifts testing to dependency boundaries, reducing integration risk and making behavior easier to verify.

Designing deep module interfaces involves generating multiple radically different architectural variants with distinct signatures and dependency strategies. You compare the hidden complexity and trade-offs of each to select a recommended direction for your refactor.

You create an architectural RFC issue by documenting the selected deepening refactor, including the involved modules, coupling reasons, and expected test impact. The Skill formats this data using a defined GitHub RFC template to propose the structural changes.

Tight coupling makes a codebase hard to test because shallow modules accumulate architectural friction across internal seams. This coupling increases integration risk and scatters behavior, preventing you from isolating logic at dependency boundaries for testing.

Yes, you can fix architectural friction across internal dependency categories by iteratively exploring the codebase. The process prioritizes deepening candidates by classifying dependencies and evaluating the expected test impact for each tightly coupled module.

You should avoid deep module refactoring when your codebase lacks clear architectural friction or internal seams. If modules are already decoupled and behavior is easily testable across existing boundaries, deepening interfaces adds unnecessary structural overhead.