Codebase Design

Design deep modules: 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 — including the agent navigating the codebase next session.

This skill is reference vocabulary, not a workflow. It carries no project facts — read .claude/PROJECT.md → Architecture for where this project's seams and layers actually live, and rules/_generic/code-quality.md for the size/naming/composition floor this builds on.

Glossary

Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point (and feeds the project's own CONTEXT.md).

• 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 — type-level surface only).
• Implementation — what's inside a module, its body of code.
• Depth — leverage at the interface: how much behaviour a caller (or test) exercises per unit of interface they must learn. Deep = large behaviour behind a small interface; shallow = interface nearly as complex as the implementation.
• Seam — a place where you can alter behaviour without editing in that place; the location 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).
• Adapter — a concrete thing that satisfies an interface at a seam. Names a role (what slot it fills), not substance. A small adapter can wrap a large implementation (a Postgres repo); a large adapter can wrap a small one (an in-memory fake).
• Leverage — what callers get from depth: more capability per unit of interface learned. 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 instead of spreading across callers. Fix once, fixed everywhere.

Deep vs shallow

Deep = small interface + lots of implementation (aim for this):

┌─────────────────────┐
│   Small interface   │  ← few methods, simple params
├─────────────────────┤
│  Deep implementation│  ← complex logic hidden
└─────────────────────┘

Shallow = large interface + thin implementation (avoid): the interface is nearly as costly to learn as the code it hides, so it buys the caller almost nothing — a pass-through wrapper, a "manager" that just forwards, getters/setters with no invariant.

When designing an interface, ask:

• Can I reduce the number of methods?
• Can I simplify the parameters?
• Can I hide more complexity inside?

Principles

• Pull complexity downward. It's better for the implementer to suffer than every caller. A messy detail handled once inside the module beats the same detail handled at every call site.
• Make modules somewhat general-purpose. A slightly more general interface is often simpler than a special-purpose one and serves more callers. Don't gold-plate — aim for "general enough."
• Define errors out of existence. The best error handling is an interface where the error can't arise (an operation that's a no-op on the empty case beats one that throws on it).
• Put the seam where behaviour must vary. Place the interface exactly at the point you'll need to swap implementations (real vs fake, prod vs test, vendor A vs B) — not one layer off. The fake/test swap alone earns it: "we will never change the provider" does not retire the seam.
• Design it twice. The first design that works is rarely the best. See DESIGN-IT-TWICE.md.
• Testable through the interface. A deep module is tested by exercising its interface with a fake at the seam — not by reaching into its implementation. If a test must mock internals, the seam is in the wrong place. This is why /tdd and /test lean on this vocabulary.

Finding deepening opportunities

Shallow modules, leaky interfaces, and misplaced seams are where a codebase rots into a ball of mud. DEEPENING.md lists the smells and the moves that deepen a module. /arch-health runs that hunt across a whole codebase; /refactor and /prepare apply it to the change at hand. WHEN-TO-CUT.md comes first when the move is a new seam: is it due, on which axis. SHAPE.md when the question is the form behind it: function or class, a subtype, a pattern's price.

How the kit uses this

• /prepare — borrow this vocabulary when weighing design alternatives and checking SOLID; a "new-abstraction" approach should be justified as a deeper module, not just more files.
• /tdd — use the depth/seam language when confirming the public interface before the first test; tests go through the seam.
• /test — a unit that needs internals mocked has its seam in the wrong place; this vocabulary names why and where to move it so tests exercise the interface.
• /refactor — D2 (architecture hygiene) is deepening work; name the smell from DEEPENING.md.
• /arch-health — the whole scan is "where are the shallow modules and bad seams?".

See also

• DESIGN-IT-TWICE.md — generate two genuinely different designs, compare, synthesize.
• DEEPENING.md — shallow-module smells and the moves that fix them.
• WHEN-TO-CUT.md — is a new seam due yet, along which axis, and what proves it.
• SHAPE.md — function, class or transform; when a subtype is legal; what a pattern costs.
• rules/_generic/code-quality.md — the size/naming/composition floor this design lens sits on.