codebase-design

A deep module hides a large amount of behaviour behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside the implementation so callers get more leverage per unit of interface they must learn.

A seam is the location where a module's interface lives and where behaviour can be altered without editing in place. 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 a production adapter and an in-memory test adapter. A single-adapter seam is just indirection and should be avoided.

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

True external dependencies like Stripe or Twilio should be injected as ports, with tests providing mock adapters. Dependencies with local stand-ins, such as PGLite for Postgres, can be tested with the stand-in running in the suite.

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