improve-codebase-architecture

To find refactoring opportunities, you can explore the codebase to identify where the deletion test suggests consolidating complexity into deeper modules. This surfaces shallow boundaries and finds areas where increasing module depth improves testability, locality, and AI agent navigability.

The deletion test is a technique used to evaluate module boundaries by assessing whether consolidating complexity into a deeper module increases leverage and locality. Applying it helps clarify seams and ensures interfaces become effective test surfaces for maintainable architecture.

To place seams and adapters effectively, you frame architectural candidates and grill them for optimal seam placement. This ensures the interface becomes the primary test surface while routing documentation for agent discovery, resulting in a robust testing strategy.

Yes, you can use ADR-informed design during refactoring to surface architectural friction. It flags conflicts when a proposed refactoring candidate contradicts a recorded architectural decision, ensuring new module boundaries align with existing project constraints.

The best way to make a codebase navigable for AI agents is to deepen modules and place seams so documentation is explicitly routed for agent discovery. This reduces architectural friction by ensuring interfaces are clear and dependencies are easy to test.

You should avoid deepening modules when the deletion test shows that consolidating complexity would reduce locality or create conflicts with existing ADRs. If the current shallow interface already provides high leverage and clear test surfaces, deepening is unnecessary.