codebase-design

A deep module puts a large amount of behavior behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside the implementation. The interface includes everything a caller must know: types, invariants, ordering, error modes, and performance characteristics.

A seam is the location where a module's interface lives, a place where behavior can be altered without editing that code. The interface is the surface callers use. Seam placement is its own design decision, distinct from what goes behind it.

Introduce a port only when at least two adapters are justified, typically production plus test. One adapter means a hypothetical seam and is just indirection. Use ports for remote-owned or true external dependencies like third-party services.

Write tests at the deepened module's interface and delete old unit tests on the shallow modules. Tests should assert observable outcomes through the interface and survive internal refactors, since the interface is the test surface.

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