improve-codebase-architecture

To refactor a tangled codebase, identify shallow modules and surface deepening opportunities using CONTEXT.md vocabulary and ADRs. This approach validates refactors with tests and guides architecture decisions to improve testability and AI-navigability.

A deepening opportunity is a refactor that turns shallow modules into deep ones to improve locality and leverage. It addresses architectural friction in tangled codebases, aiming to enhance testability and AI-navigability.

ADRs guide refactoring by aligning deepening opportunities with documented architecture decisions. Reading ADRs alongside a domain glossary identifies friction points and validates proposed refactors through a grilling workflow.

Yes, this approach specifically targets large codebases with tangled modules. It leverages CONTEXT.md vocabulary and a grilling workflow to surface actionable deepening candidates and ADR-aligned refactors for complex architectures.

The best way to surface architectural friction is reading a domain glossary and ADRs to identify friction points, then conducting a grilling loop. This refines designs and proposes concrete deepening opportunities for shallow modules.

Deepening refactors target large codebases with tangled modules and shallow architectures. If your codebase is small, already deeply structured, or lacks ADRs and CONTEXT.md documentation, this grilling workflow approach may not apply.