codebase-design

name	codebase-design
tier	core
runtime	on-demand
trigger	mention
description	Shared vocabulary for designing deep modules — module / interface / depth / seam / adapter / leverage / locality, the deletion test, deep-vs-shallow. Use when designing or improving a module's interface, deciding where a seam goes, making code testable or AI-navigable, or when another skill (dag-deepen / dag-slim) needs the design vocabulary. Trigger: design this module / where should the seam go / is this module too shallow / deep module / deletion test / codebase-design. Skip: finding what to refactor (/dag-deepen) / finding what to delete (/dag-slim) / reviewing a diff (/dag-review).
metadata	{"source":"oh-my-dag","version":"1.0.0","methodology":"Ousterhout deep modules + Feathers seams; single source shared with src/harness/review/design-vocab.ts"}

codebase-design — deep-module vocabulary

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this exact language wherever code is being designed or restructured — consistent vocabulary is the whole point. The machine-readable twin of this glossary lives in src/harness/review/design-vocab.ts (injected into dag-deepen / dag-slim prompts); keep the two in sync.

Glossary

Use these terms exactly — never substitute "component," "service," "API," or "boundary."

• Module — anything with an interface and an implementation; deliberately scale-agnostic (a function, class, package, or tier-spanning slice).
• Interface — everything a caller must know to use the module correctly: type signature plus invariants, ordering constraints, error modes, required configuration, performance characteristics.
• Implementation — the code body inside a module.
• Depth — leverage at the interface: behaviour exercised per unit of interface learned. Deep = small interface hiding lots of behaviour. Shallow = interface nearly as complex as the implementation (avoid).
• Seam (Feathers) — a place where you can alter behaviour without editing in that place; where an interface lives. Placement is its own design decision.
• Adapter — a concrete thing satisfying an interface at a seam; names the role. One adapter = hypothetical seam; two = real.
• Leverage — what callers get from depth: 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. Fix once, fixed everywhere.

Judgments

• Deletion test — imagine deleting the module and inlining its logic into callers: complexity explodes → it truly absorbs complexity (deep); barely changes → shallow, or outright noise to delete. (The same test prunes prose and skills, not just code.)
• The interface is the test surface — if you can't test through the interface, the design is wrong, not the test.
• Wide over deep applies to DAGs, deep over shallow applies to modules — don't confuse the two axes.