Codebase Design

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AbyssCN
• Source: AbyssCN/oh-my-dag
• License: MIT

Install and usage instructions live in the source repository linked above.