mp-codebase-design

---
name: mp-codebase-design
description: "Use when designing or improving a module's interface, finding deepening opportunities, deciding where a seam goes, or making code more testable — a shared vocabulary for deep modules."
source: https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md
generated: 2026-07-08T18:57:47.903Z
category: concept
audience: engineers
---

## When to use

- Designing or restructuring a module's interface
- Looking for deepening opportunities in an existing codebase
- Deciding where a seam should go, or whether one is warranted at all
- Making code more testable or easier for an agent to navigate

## Key concepts

### Deep module

A lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Deep = large implementation behind a small interface; shallow = interface nearly as complex as the implementation (avoid).

### Interface vs implementation vs adapter

Interface = everything a caller must know (types, invariants, ordering, error modes, perf), not just the signature. Implementation = the body inside. Adapter = a concrete thing satisfying an interface at a seam (describes role, not substance).

### Seam (Feathers)

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, separate from what goes behind it. Avoid the word 'boundary' (overloaded with DDD).

### Depth, leverage, locality

Depth = behaviour exercised per unit of interface learned. Leverage = what callers gain from depth (capability per unit learned). Locality = what maintainers gain (change, bugs, verification concentrate in one place — fix once, fixed everywhere).

### 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. Related: one adapter means a hypothetical seam; two adapters means a real one.

## Gotchas

- Use the glossary terms exactly — don't substitute 'component', 'service', 'API', or 'boundary'; consistent language is the point
- Depth is a property of the interface, not the implementation — a deep module can still be internally composed of small mockable parts
- The interface is the test surface; if you want to test past the interface, the module is probably the wrong shape
- Don't introduce a seam unless something actually varies across it

---
Generated by SkillMake from https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md on 2026-07-08T18:57:47.903Z.
Verify against source before relying on details.

File: ~/.claude/skills/mp-codebase-design/SKILL.md