| name | codebase-design |
| description | Shared vocabulary for designing deep modules and for naming factory concepts consistently. Load before writing a spec, decomposing issues, freezing checks, or reviewing a diff - anywhere "module," "interface," "issue," or "frozen check" need to mean the same thing to every skill, builder, and reviewer. Also covers dependency categories for deepening and the parallel design-it-twice pattern for exploring interfaces before committing to one.
|
Codebase Design
Design deep modules: a lot of behavior behind a small interface, placed
at a clean seam, testable through that interface. Use this language wherever
code or a factory issue is being designed. The aim is leverage for callers,
locality for maintainers, and testability for everyone.
Glossary
Use these terms exactly — don't substitute component, service, boundary, or API
when you mean module or interface; don't say task or ticket for issue, or test
file for frozen check. Consistent language is the whole point.
Design (Pocock, adapted):
- Module - anything with an interface and an implementation, at any scale: a function, a package, or a whole vertical slice.
- Interface - everything a caller must know to use a module correctly: types, invariants, ordering, error modes, config, performance - not just a signature.
- Implementation - the body of code behind the interface; distinct from adapter, which names role at a seam, not substance.
- Depth - leverage at the interface: behavior reached per unit of interface learned. Deep means a small interface over a big implementation; shallow is the opposite, and to avoid.
- Seam (Feathers) - the place a module's interface lives; where behavior can change without editing there.
- Adapter - a concrete thing satisfying an interface at a seam. One adapter is a hypothetical seam; two make it real.
- Leverage - what callers get from depth: one implementation pays off across many call sites and tests.
