codebase-design

Start by reducing the number of methods and simplifying parameters so more behavior hides behind less surface. Accept dependencies rather than creating them, return results rather than producing side effects, and verify depth with the deletion test: if deleting the module pushes complexity into callers, it earns its keep.

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 everything a caller must know to use the module: signatures, invariants, ordering, error modes, and performance characteristics.

Introduce a port only when at least two adapters are justified, typically a production adapter and a test adapter. A single-adapter seam is just indirection. Use ports for remote-owned or third-party dependencies so tests can substitute in-memory or mock adapters.

Write tests at the deepened module's interface, treating the interface as the test surface, and delete old unit tests on the shallow modules it absorbed. Use local stand-ins like in-memory databases for substitutable dependencies and mock adapters only for true external services.

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 common-case optimization. The designs are then compared on depth, locality, and seam placement, with an opinionated recommendation.