# Codebase Design > Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. - Skill: `paulrberg/codebase-design` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add paulrberg/codebase-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulrberg/codebase-design/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: paulrberg (https://skillmd.com/u/paulrberg) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/paulrberg/codebase-design --- # Codebase Design Design **deep modules**: substantial behaviour behind a small interface at a clean seam, testable through that interface. Use this vocabulary when it clarifies a design decision. The aim is leverage for callers, locality for maintainers, and testability. ## Glossary Use these terms consistently where their distinctions matter. **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). **Leverage** — what callers get from depth: more capability per unit of interface they learn. 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 rather than spreading across callers. Fix once, fixed everywhere. ## Deep vs shallow **Deep module** — small interface (few methods, simple params) hiding a lot of implementation. **Shallow module** (avoid) — interface nearly as large as its thin, pass-through implementation. When designing an interface, ask: - Can I reduce the number of methods? - Can I simplify the parameters? - Can I hide more complexity inside? ## Principles - **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test _past_ the interface, the module is probably the wrong shape. - **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. ## Designing for testability Good interfaces make testing natural: - At a real seam, accept the dependency as a parameter instead of constructing it inside the module. - Prefer returning results to side effects when that keeps the interface simpler. - Keep the surface small: fewer methods and parameters mean fewer, simpler tests. ## Relationships - A **Module** has exactly one **Interface** (the surface it presents to callers and tests). - **Depth** is a property of a **Module**, measured against its **Interface**. - A **Seam** is where a **Module**'s **Interface** lives. - An **Adapter** sits at a **Seam** and satisfies the **Interface**. - **Depth** produces **Leverage** for callers and **Locality** for maintainers. ## Rejected framings - **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. - **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. - **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. ## Output Contract When applying this vocabulary to a design or review, report the recommended module, interface, and seam; explain how the result improves depth, leverage, locality, or testability; and identify material tradeoffs or unresolved evidence. When this skill is only supporting another requested artifact, incorporate that analysis into the artifact instead of adding a separate report. ## Going deeper - **Deepening a cluster given its dependencies** — see [references/DEEPENING.md](references/DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing. - **Exploring alternative interfaces** — see [references/DESIGN-IT-TWICE.md](references/DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement. Forked from [mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design).