Codebase Design — Deep Modules

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this vocabulary and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.

Glossary

Use these terms for the concepts below; they disambiguate "component," "service," "API," or "boundary" when those words are being used loosely for different things in the same discussion.

Deep vs Shallow

A deep module has a small interface over a deep implementation; a shallow one has a large interface over a thin, mostly pass-through implementation (avoid). When designing an interface, ask:

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

Core Principles

Depth is a property of the interface, not the implementation. A deep module can be internally composed of many small, swappable parts — they just are not part of the external interface. A module can have internal seams (private to its implementation) as well as the external seam at its interface.

The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through and is earning nothing. 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.

Two adapters are evidence of a real seam, not a requirement for one. A second adapter (typically production + test stand-in) proves something varies across the boundary, which is why it is the easiest justification to check. But it is one sufficient reason, not the only one. A seam is also justified by:

• independent volatility — the two sides change for different reasons, on different cadences;
• an external contract — the boundary is where a protocol, schema, or published API is honoured;
• a security boundary — trust, authorization, or tenancy changes across it, and collapsing it would erase the place the check belongs.

What is not a justification is a seam added because a second implementation might appear someday. Absent one of the reasons above, the seam is speculative — the cost is real now and the variation is hypothetical.

Designing for Testability

Good interfaces make testing natural without special arrangements:

1. Accept dependencies, do not create them. Inject the gateway into the function instead of constructing it inside.
2. Return results, do not produce side effects invisibly. An observable return value tests directly; a mutation of shared state does not.
3. Small surface area. Fewer methods = fewer tests needed. Fewer parameters = simpler test setup.

Design Workflow

When applying this skill to a module or cluster:

1. Name it. Agree on module, interface, seam, and adapter — use the glossary terms above, not local synonyms.
2. Measure depth. Apply the deletion test: if complexity vanishes on deletion, the module is shallow. Count how much a caller must know vs how much behaviour they get.
3. Classify dependencies. Use the 4 categories in references/deepening.md (in-process / local-substitutable / remote-but-owned / true-external) to decide the testing approach.
4. Find the seam. Decide where the interface lives — this is independent of what goes behind it. Justify it with evidence: a second adapter, independent volatility, an external contract, or a security boundary. A seam with none of those is speculative.
5. Explore alternatives — the exception, not the default. Design it once and move on; reach for references/design-it-twice.md's parallel sub-agent pattern only for a genuinely high-stakes, hard-to-reverse seam where the right interface is still uncertain after step 4. When it applies: compare candidates on depth/locality/seam, pick the strongest or propose a hybrid, using the specialist subagent the runtime lists by task type (generic/default only when none fits).
6. Validate. Apply the interface-as-test-surface check: tests cross the same seam as callers. If tests need to reach past the interface, the module shape is wrong.

Checking for Shallow Modules

When asked to find or assess shallow modules, examine concrete candidates and apply the deletion test to each. A single caller, a single adapter or a thin wrapper is a lead, never proof: name what the boundary protects (volatility, contract, security, testability) and where its complexity would land without it. A caller count from rg misses dynamic dispatch, registrations, configuration and external consumers. For each candidate say delete, inline, deepen or keep, with that reason; this skill gives the design verdict and kill-slop owns the proof that a deletion is safe, so change code only when asked and delete through kill-slop's proof rules. Neither skill sets a size threshold for the verdict. A repo-wide ranked report of deepening opportunities is a larger exercise than this check: run it as its own piece of work, interviewing the owner on each candidate before changing anything.

Reference Files

• Read references/deepening.md to deepen a cluster of shallow modules: 4 dependency categories, seam discipline, replace-don't-layer testing strategy.
• Read references/design-it-twice.md only for the rare high-stakes, hard-to-reverse seam that stays uncertain after step 4, never as the default design path: parallel sub-agent pattern sized to the genuinely distinct candidates worth comparing, compare on depth/locality/seam, give an opinionated recommendation.

Attribution

Adapted from mattpocock/skills (MIT). Original skill: codebase-design.