codebase-design

Codebase design

Contract

Inputs

• Required: one named target module (a function, class, package, crate, or tier-spanning slice) with readable source and enough of its callers and tests to judge what they must know.
• Optional: intended adapters, candidate seam locations, and the target language, which is inferred from the source when not stated.

Procedure

1. Bound the scope. Name exactly one target module and confirm its source is readable; a name matching nothing is an unbounded-target stop, not a guess. Read the interface surface, the implementation, and the callers and tests crossing them. If depth cannot be judged inside this scope, stop and name the missing evidence. Done when: one module is named, its source is read, and its callers and tests are surveyed.
2. Fix the vocabulary. Use these terms exactly; do not substitute near-synonyms.
   • Module: anything with an interface and an implementation, scale-agnostic from a single function to a tier-spanning slice. Avoid: "unit," "component," "service."
   • Interface: everything a caller must know: type signature, invariants, ordering constraints, error modes, required configuration, performance characteristics. Avoid: "API," "signature"; they name only the type-level surface.
   • Implementation: the body inside the module. A small adapter can hold a large implementation (a Postgres or JPA repository) and a large adapter a small one (an in-memory fake); say "adapter" when the seam is the topic, "implementation" otherwise.
   • Seam (Michael Feathers): a place where behaviour can be altered without editing in that place; it is where the module's interface lives. Avoid: "boundary"; it is overloaded with DDD's bounded context.
   • Adapter: a concrete thing that satisfies an interface at a seam; it names the role, not the substance.
   • Depth: the behaviour a caller or test can exercise per unit of interface it must learn. Deep means large behaviour behind a small interface; shallow means the interface is nearly as complex as the implementation.
   • Leverage: what callers get from depth: capability per unit of interface learned, one implementation paying back across N call sites and M tests.
   • Locality: what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place; fix once, fixed everywhere. Done when: the vocabulary is fixed and no near-synonym substitution remains.
3. Classify depth by leverage, not line ratio. Depth is a property of the interface, not the implementation: internal parts, including internal seams used only by the module's own tests, are not interface, and a module has exactly one interface. A single method that handles a hard problem well is deeper than ten methods that each forward to another layer. Done when: a deep/shallow classification is stated with leverage evidence.
4. Run the deletion test. Imagine deleting the module: if the complexity vanishes, it was a pass-through hiding nothing; if the complexity reappears across N callers, it is earning its keep. Done when: the deletion test produces a pass-through or earning-its-keep verdict.
5. Narrow the interface. Ask in order: can methods be reduced? can parameters be simplified? can more complexity be hidden inside? Prefer the form that gives callers leverage and maintainers locality. Done when: the interface is at its narrowest form that preserves caller-visible behavior.
6. Place seams by variation. The external seam carries the interface; internal seams stay private to the implementation and its tests. Introduce a seam only when something actually varies across it: one adapter means a hypothetical seam, two adapters mean a real one. Done when: every seam is placed where variation actually crosses it.
7. Check the test surface. Callers and tests cross the same seam; a test that must reach past the interface means the module is the wrong shape. Restructure by accepting dependencies instead of constructing them (process_order(order, gateway) with an injected gateway is testable; an internal StripeGateway() construction is not), returning results instead of mutating (calculate_discount(cart) -> Discount is testable; mutating cart.total in place is not), and keeping the surface small: fewer methods mean fewer tests, fewer parameters mean simpler setup. Done when: callers and tests cross the same seam without reaching past the interface.
8. Anchor terms in the target language. See references/language-anchors.md for the per-language module, interface, seam, and adapter mappings (Rust, Go, OCaml, Java/Kotlin). Done when: the vocabulary is anchored in the target language's constructs.
9. Reject these framings wherever they appear. Depth measured as a ratio of implementation lines to interface lines rewards padding the implementation: use depth-as-leverage. "Interface" narrowed to the language keyword or a class's public methods is too narrow: the interface is every fact a caller must know. Done when: both rejected framings are checked and neither is present in the analysis.
10. Deliver, then edit. Emit the recommendation in the fixed vocabulary; when restructuring is in scope, apply local edits confined to the bounded module while every caller and test keeps crossing the same seam. Done when: the recommendation is delivered and any local edits are applied within the bounded module.