codebase-design

A deep module hides substantial behavior behind a small interface. Reduce method count, simplify parameters, and move complexity behind the interface. Judge depth by leverage: how much behavior callers gain per unit of interface they must learn.

A seam, from Michael Feathers, is a location where behavior can change without editing that code—where a module's interface sits. Introduce a seam only when at least two adapters justify it, such as a production adapter plus a test adapter.

Use ports and adapters for remote-but-owned services and truly external third-party dependencies. Define a port at the seam, inject an HTTP or queue adapter in production, and use in-memory or mock adapters in tests.

Testable interfaces receive dependencies rather than creating them, return results rather than producing side effects, and keep the surface small. The interface is the test surface—tests assert observable behavior through it, not internal state.

Design It Twice launches three or more parallel subagents, each producing a contrasting interface under different constraints such as minimal surface or maximum flexibility. Designs are then compared on depth, locality, and seam placement before recommending one.

Delete old unit tests on shallow modules once the deepened module's interface has its own tests. Tests should target the interface and survive internal refactoring; keeping redundant tests on internals creates maintenance burden.