codebase-design

A deep module puts a large amount of behaviour behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside. Ask whether deleting the module would remove complexity or just push it back onto callers.

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

Introduce a port only when at least two adapters are justified, typically production plus test. A single-adapter seam is just indirection. Use ports for remote-but-owned services and true external dependencies like Stripe.

Accept dependencies as parameters instead of constructing them, return results instead of producing side effects, and keep the surface area small. Tests should assert observable outcomes through the interface and survive internal refactors.

Design It Twice spawns three or more parallel sub-agents, each producing a radically different interface under different constraints such as minimal surface or maximum flexibility. The designs are then compared on depth, locality, and seam placement.

Delete old unit tests on shallow modules once tests exist at the deepened module's interface. The interface becomes the test surface, and tests targeting internals become waste that breaks on every refactor.