a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
Glossary
Use these terms exactly — don't substitute "component," "service," "API," or "boundary." 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, and performance characteristics.
Avoid
API, signature (too narrow — they refer only to the type-level surface).
Implementation
— what's inside a module, its body of code. 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). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
Depth
— leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is
deep
when a large amount of behaviour sits behind a small interface,
shallow
when the interface is nearly as complex as the implementation.
Seam
(Michael Feathers)
— a place where you can alter behaviour without editing in that place; the
location
at which 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 that satisfies an interface at a seam. Describes
role
(what slot it fills), not substance (what's inside).
Show more
Installs
1.7K
Repository
mattpocock/skills
GitHub Stars
132.4K
First Seen
13 days ago
Security Audits
Gen Agent Trust Hub
Pass
Socket
Pass
Snyk
Pass