codebase-design

Design deep modules: substantial behavior behind a small interface at a clean seam, testable through that interface. Optimize caller leverage, maintainer locality, and testability.

Depth must improve semantic density now. No modules, seams, adapters, or interfaces for hypothetical reuse. A design wins only when it removes more caller knowledge/coordination than it adds.

Glossary

Use exactly:

Module -- interface plus implementation: function, class, package, slice.

Interface -- everything callers know: types, invariants, ordering, errors, config, performance; broader than signature.

Implementation -- module internals.

Depth -- interface leverage. Deep means small interface/large behavior; shallow means similar interface and implementation complexity.

Seam -- where behavior can vary without editing the caller; its interface lives here. Avoid: boundary, except DDD bounded context.

Adapter -- concrete implementation at a seam, named by role.