codebase-design

Start by reducing the number of methods and simplifying parameters so more behaviour hides behind less surface. Accept dependencies rather than creating them, return results instead of producing side effects, and verify depth with the deletion test: if deleting the module spreads complexity across callers, it earns its keep.

A seam is the location where a module's interface lives, a place where behaviour can be altered without editing that spot. The interface is everything a caller must know to use the module: types, invariants, ordering, error modes, and performance characteristics.

Introduce a port only when at least two adapters are justified, typically a production adapter and an in-memory test adapter. A single-adapter seam is just indirection; one adapter means a hypothetical seam, two adapters mean a real one.

Write tests at the deepened module's interface, treating the interface as the test surface, and delete old unit tests on the shallow modules it replaced. Tests assert observable outcomes through the interface so they survive internal refactors.

It frames the problem space and constraints, then spawns three or more parallel sub-agents that each design a radically different interface under distinct constraints such as minimal surface or maximum flexibility. The designs are compared on depth, locality, and seam placement, followed by an opinionated recommendation.

Avoid deepening when a dependency has no local test stand-in and no justified second adapter, or when the module is a genuine pass-through where merging adds no leverage. Forcing a seam without variation across it only adds indirection.