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 the implementation. Measure depth as leverage: how much behaviour callers get per unit of interface they must learn.

An interface is everything a caller must know to use a module, including invariants, ordering, and error modes. A seam is the location where that interface lives, a place where behaviour can be altered without editing in place. Seam placement is its own design decision.

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. This applies to remote-but-owned services and true external dependencies like third-party APIs.

Write tests at the deepened module's interface, treating the interface as the test surface. Delete old unit tests on the shallow modules it replaced, and assert on observable outcomes rather than internal state so tests survive internal refactors.

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