# Deep Modules

> Design vocabulary for deep modules, a lot of behaviour behind a small interface placed at a clean seam and testable through that interface. Use when designing or reshaping a module's public interface, deciding where a boundary goes, judging whether an abstraction earns its keep, or when another skill needs the module / interface / depth / seam terms. A reference to consult, not a session to run.

- Skill: `presidenteog/deep-modules` (Agent Skill)
- Install (CLI): `npx skillmds@latest add presidenteog/deep-modules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/presidenteog/deep-modules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: PresidenteOG (https://skillmd.com/u/presidenteog)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/presidenteog/deep-modules

---


# Deep Modules

Adapted from https://github.com/mattpocock/skills (mattpocock/skills, MIT), which draws on John Ousterhout's *A Philosophy of Software Design* — rewritten, not copied.

## The terms
| Term | Meaning |
|---|---|
| Module | Any unit with an inside and an outside: a function, a file, a class, a package |
| Interface | What a caller must know to use the module: signatures plus the informal contract |
| Depth | Ratio of behaviour to interface. Deep = much behaviour, small interface. Shallow = interface nearly as large as the implementation |
| Seam | The boundary where you observe behaviour without reaching inside; where tests attach |
| Adapter | A thin module translating one interface to another; pushes a mess into one place |
| Leverage | How much a change behind the interface buys you without callers noticing |
| Locality | Related things kept close; a change touches one place, not ten |

## Using it
- **Prefer deep.** A module earns its interface by hiding more than it exposes. If the interface is nearly as complex as what it hides, inline it: the abstraction is a tax.
- **Put the seam where behaviour is observable and stable, and test there.** If the seam keeps moving, the module's responsibility is not decided yet.
- **Information hiding is the point.** Each design decision known to one module and not leaked through its interface is leverage banked.
- **Pull complexity downward.** Better for the module to be complicated than its interface.

## Relation to other skills
Feeds `test-seams` (tests attach at seams) and `context-glossary` (module names come from the domain terms). Not a substitute for `refactoring-ui` (visual polish) or `tech-debt-auditor` (finds existing debt): this is the vocabulary for the design conversation itself.