codebase-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codebase Design

The shared design language for module depth, interfaces, seams, and adapters. One
home for the deep-module vocabulary so the terms mean the same thing in every
skill that reasons about architecture — `/improve-codebase-architecture`, `/tdd`,
and anything else that touches interface design composes this skill instead of
carrying its own copy.

Most terms come from two books — **A Philosophy of Software Design** (Ousterhout,
"APoSD") and **Clean Architecture** (Martin) — bundled as decision-pressure rules
into the skills that consume this vocabulary. When we use a book's term, we use it
the way the book uses it. A few terms are ours, added where the books don't have a
precise name for what we mean.

## Vocabulary

**Module** *(both books)*
Anything with an interface and an implementation. Scale-agnostic — applies equally
to a function, class, package, or tier-spanning slice. APoSD: a *deep* module has a
small interface hiding a large body of behaviour; a *shallow* module has an
interface nearly as wide as its implementation.
_Avoid_: unit, component, service.

**Interface** *(both books)*
Everything a caller must know to use the module correctly. Includes the type
signature, but also invariants, ordering constraints, error modes, required
configuration, and performance characteristics. Clean Architecture calls
inward-owned interfaces **ports** (see below).
_Avoid_: API, signature (too narrow — those refer only to the type-level surface).

**Implementation** *(APoSD)*
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 repository) or a large
adapter with a small implementation (an in-memory fake).

**Depth** *(APoSD)*
Leverage at the interface: a lot of behaviour behind a small interface. **Deep** =
high leverage. **Shallow** = interface nearly as complex as the implementation.

**Boundary** *(Clean Architecture)*
A line across which source dependencies cross in one direction only. Enforces the
dependency rule: dependencies point inward toward higher-level policy. A boundary
is a particular kind of **seam** — one that also enforces a dependency direction.

**Layer** *(Clean Architecture)*
A horizontal stack of modules at the same level of policy. The inward direction is
*upward* in policy (more general, more stable). Not interchangeable with
**module** — a layer is the stack; a module is a unit within it.

**Port** *(Clean Architecture)*
An interface owned by an inner layer, implemented by an outer-layer adapter. Use
"port" when the dependency-direction property is the point; otherwise just
**interface**.

**Adapter** *(Clean Architecture)*
A concrete thing that satisfies an interface at a seam or boundary. Describes *role*
(what slot it fills), not substance (what's inside). **Humble** adapters do *only*
translation between external formats and the use-case call — no business decisions.

**Cognitive load / Change amplification / Hidden dependencies / Temporal coupling** *(APoSD)*
The dimensions a deep module reduces. Use these names when describing *why* a
deepening helps:

- **Cognitive load** — total facts a reader must hold at once.
- **Change amplification** — one conceptual change requiring many code changes.
- **Hidden dependencies** — knowledge required to use the module that isn't visible
  at the interface.
- **Temporal coupling** — operations that must be called in a specific order; almost
  always a sign of a shallow module exposing its phases.

### Our additions

Where the bundled books don't have a precise term, we've added these.

**Seam** *(from Michael Feathers, Working Effectively with Legacy Code — also bundled in /tdd's rules)*
A place where behaviour can be altered without editing in that place. The *location*
at which a module's interface lives. Choosing where to put the seam is its own design
decision, distinct from what goes behind it.

A **boundary** in Clean Architecture's sense is a particular kind of seam — one that
also enforces a dependency direction. Prefer **seam** when the topic is testability
and substitution; **boundary** when the topic is policy/detail separation.

**Depth-as-leverage**
We measure depth as *behaviour per unit of interface a caller has to learn*. APoSD
also frames depth as a ratio of implementation lines to interface lines; we don't use
the ratio because it rewards padding the implementation. Both framings agree on what
makes a module shallow.

**Leverage**
What callers get from depth. More capability per unit of interface they have to learn.
One implementation pays back across N call sites and M tests. Not a book term — added
because the concept is useful enough to name.

**Locality**
What maintainers get from depth. Change, bugs, knowledge, and verification concentrate
at one place rather than spreading across callers. Fix once, fixed everywhere. Not a
book term — same reason.

## Deep vs shallow modules

**Deep module** = small interface + lots of implementation

```
┌─────────────────────┐
│   Small Interface   │  ← Few methods, simple params
├─────────────────────┤
│                     │
│                     │
│  Deep Implementation│  ← Complex logic hidden
│                     │
│                     │
└─────────────────────┘
```

**Shallow module** = large interface + little implementation (avoid)

```
┌─────────────────────────────────┐

From ZunoSmartLabs/zsl-superpowers, MIT.

More from ZunoSmartLabs/zsl-superpowers