design

Design

Part of the Plan/Build phases — see the workflow skill for tiers and sequencing.

Design deep modules: a lot of behaviour 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. Mostly T2/T3 territory.

Glossary

Use these terms exactly — consistent language is the whole point.

Module — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service.

Interface — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, performance characteristics. Avoid: API, signature (too narrow — type-level surface only).

Implementation — what's inside a module. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake).

Depth — leverage at the interface: how much behaviour a caller (or test) can exercise per unit of interface they must learn. Deep = lots of behaviour behind a small interface; shallow = interface nearly as complex as the implementation.

Seam (Michael Feathers) — a place where you can alter behaviour without editing in that place; where a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. Avoid: boundary (overloaded with DDD's bounded context).

Adapter — a concrete thing satisfying an interface at a seam. Describes role, not substance.

Leverage — what callers get from depth: one implementation pays 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.

Deep vs shallow

Deep (aim for this):            Shallow (avoid):
┌───────────────┐               ┌───────────────────────────────┐
│ Small interface│              │        Large interface        │
├───────────────┤               ├───────────────────────────────┤
│               │               │      Thin implementation      │
│ Deep implemen- │              └───────────────────────────────┘
│ tation        │
└───────────────┘