codebase-design
Codebase Design
Purpose
Design 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. This skill is the shared vocabulary other skills consult — a reference, not a session to run.
Vocabulary
-
Use these terms for findings that need precise module vocabulary; do not replace them when they accurately describe the design:
-
Module: anything with an interface and an implementation — scale-agnostic (function, class, package).
-
Interface: everything a caller must know to use the module correctly — the signature plus invariants, ordering constraints, error modes, configuration, and performance characteristics.
-
Depth: leverage at the interface — how much behavior a caller or test can exercise per unit of interface learned. Deep = lots of behavior, small interface. Shallow = interface nearly as complex as the implementation.
-
Seam: the location where a module's interface lives — where behavior can be altered without editing in that place. Where the seam goes is its own design decision, distinct from what sits behind it.
-
Adapter: a concrete thing satisfying an interface at a seam — describes role, not substance.
-
Leverage: what callers get from depth — one implementation paying back across N call sites and M tests.
-
Locality: what maintainers get from depth — change, bugs, and knowledge concentrate in one place; fix once, fixed everywhere.