Design deep modules with small interfaces and testable seams

Codebase Design provides a shared vocabulary for designing deep modules: a lot of behavior behind a small interface, placed at a clean seam, testable through that interface. The aim is leverage for callers, locality for maintainers, and testability for everyone - and it insists on exact terms rather than substitutes like "component," "service," "API," or "boundary," because consistent language is the whole point. Glossary: Module (anything with an interface and implementation - deliberately scale-agnostic, a function/class/package/tier-spanning slice); Interface (everything a caller must know to use the module correctly - type signature plus invariants, ordering constraints, error modes, configuration, and performance characteristics, broader than "API" or "signature"); Implementation (what's inside a module, distinct from Adapter - a thing can be a small adapter with a large implementation, like a Postgres repo, or a large adapter with a small implementation, like an in-memory fake); Depth (leverage at the interface - how much behavior a caller can exercise per unit of interface learned; deep = small interface + lots of implementation, shallow = interface nearly as complex as the implementation, to be avoided); Seam (Michael Feathers' term - a place where behavior can be altered without editing there, distinct from what goes behind it); Adapter (a concrete thing satisfying an interface at a seam - describes role, not substance); Leverage (what callers get from depth - one implementation pays back across N call sites and M tests); Locality (what maintainers get from depth - change, bugs, and knowledge concentrate in one place instead of spreading).

Use it when designing or improving a module's interface, finding deepening opportunities, deciding where a seam goes, making code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. Use this language wherever code is being designed or restructured.

Four design principles: depth is a property of the interface, not the implementation (a deep module can be internally composed of small mockable parts that just aren't part of the interface); the deletion test (imagine deleting the module - if complexity vanishes it was a pass-through, if it reappears across N callers it was earning its keep); the interface is the test surface (if you want to test past the interface, the module is probably the wrong shape); and one adapter means a hypothetical seam, two adapters means a real one - don't introduce a seam unless something actually varies across it. Testability guidance: accept dependencies rather than creating them internally (pass a paymentGateway in rather than new StripeGateway() inside), return results rather than producing side effects, and keep a small surface area since fewer methods and params mean fewer tests and simpler setup.

The relationship model chains cleanly: a Module has exactly one Interface; Depth is a property of a Module measured against its Interface; a Seam is where a Module's Interface lives; an Adapter sits at a Seam and satisfies the Interface; Depth produces Leverage for callers and Locality for maintainers. It explicitly rejects Ousterhout's depth-as-implementation-to-interface-line-ratio framing (rewards padding), narrow readings of "interface" as just a TypeScript keyword or public methods, and "boundary" (overloaded with DDD's bounded context). Related docs go deeper: DEEPENING.md for deepening a cluster given its dependencies, and DESIGN-IT-TWICE.md for spinning up parallel sub-agents to design an interface several radically different ways and compare on depth, locality, and seam placement.

Developers and design-reviewing agents who need a precise, shared vocabulary for module design decisions - especially deciding whether an interface is doing too little (shallow) or correctly hiding complexity (deep) - instead of talking past each other with overloaded generic terms.