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

An interface is everything a caller must know to use a module, including invariants, error modes, and ordering constraints. A seam is the location where that interface lives, a place where behavior can be altered without editing in place.

Use ports and adapters when a dependency crosses a network boundary you own, such as internal microservices. Only introduce a seam when at least two adapters are justified, typically a production adapter and an in-memory test adapter.

Accept dependencies as parameters instead of constructing them, return results instead of producing side effects, and keep the surface area small. Write tests at the module's interface and delete old unit tests on shallow modules once interface-level tests exist.

Depth measured as implementation-lines to interface-lines rewards padding, so this Skill uses depth-as-leverage instead. A single-adapter seam is just indirection, and exposing internal seams through the interface breaks the module's shape.