module-designlisted

# Module Design Shape modules so a small, stable interface hides substantial implementation. The unit of design is the interface a caller sees, not the code behind it. Add an abstraction only when it earns the indirection it introduces. ## What a deep module looks like - Small interface, substantial body: much hidden behind little exposed. Depth is a property of the interface, not the line count. - Callers depend on what it does, never on how. A change to the implementation must not ripple outward. - The interface is the test surface. If it is hard to test without reaching inside, the boundary is wrong. ## Design moves - Deletion test: if removing the module scatters its knowledge back into callers, it encapsulates nothing — inline it. - Adapter rule: one implementation behind an abstraction is a hypothetical seam; two is a real one. Add the interface when the second appears. - Inject dependencies and return results rather than reaching for globals or firing hidden side effects. - Push complexity down (absorb hard cases) instead of out (handing edge cases back to every caller). ## Guardrails - Prefer composition of small functions over inheritance and framework hooks. - Refuse the shallow wrapper, the premature adapter, configuration-driven indirection no caller varies, and interfaces that leak internal types or state. - Present the simplest shape first and justify every layer against its indirection cost. - Distinct from architect (system-level decisions) and rfc: thi