codebase-design

Installation
SKILL.md

Codebase Design

Purpose

Design deep modules: a lot of behavior behind a small interface, placed at a clean seam, testable through that interface. The aim is leverage for callers, locality for maintainers, and testability for everyone. This skill is the shared vocabulary other skills consult — a reference, not a session to run.

Vocabulary

  • Use these terms for findings that need precise module vocabulary; do not replace them when they accurately describe the design:

  • Module: anything with an interface and an implementation — scale-agnostic (function, class, package).

  • Interface: everything a caller must know to use the module correctly — the signature plus invariants, ordering constraints, error modes, configuration, and performance characteristics.

  • Depth: leverage at the interface — how much behavior a caller or test can exercise per unit of interface learned. Deep = lots of behavior, small interface. Shallow = interface nearly as complex as the implementation.

  • Seam: the location where a module's interface lives — where behavior can be altered without editing in that place. Where the seam goes is its own design decision, distinct from what sits behind it.

  • Adapter: a concrete thing satisfying an interface at a seam — describes role, not substance.

  • Leverage: what callers get from depth — one implementation paying back across N call sites and M tests.

  • Locality: what maintainers get from depth — change, bugs, and knowledge concentrate in one place; fix once, fixed everywhere.

Installs
4
First Seen
Oct 13, 2026