Codebase Design

Design deep modules: a lot of behaviour 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.

Why

Complexity is the enemy. It shows up as:

• Change amplification: a simple change touches many places.
• Cognitive load: you must hold a lot in your head to change anything safely.
• Unknown unknowns: it is not obvious what you need to change or know.

It has two causes: dependencies and obscurity. Good design removes both.

Work strategically, not tactically. Working code is not enough. Each change is a small, continual investment in the design, not a patch on top of it.

Glossary

Use these terms exactly. Don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.