technical-term · Foundations · foundational · Reviewed
Deep module
A software module whose relatively simple, stable interface hides substantial implementation complexity and keeps that complexity from spreading through the codebase.
Definition
A deep module provides significant capability behind a small conceptual surface. Its depth is relative: the benefit delivered and complexity hidden are large compared with the interface a caller must understand. Deep modules can make a codebase easier for humans and agents to navigate, but excessive generalization, hidden side effects, or poorly chosen boundaries can make an apparently simple interface misleading.
Module depth is established software-design guidance; applying it specifically to agent-readable repositories is a current practitioner synthesis.
Why it matters
Every public concept consumes attention and model context. A well-chosen boundary lets callers reason locally without loading internal machinery.
Depth comes from information hiding and coherent responsibility, not from placing a large amount of unrelated code behind a short function name.
System anatomy
- Small interface
- Few concepts and operations for callers to learn.
- Hidden complexity
- Implementation decisions remain inside the responsible boundary.
- Coherent responsibility
- The module owns a meaningful capability rather than unrelated convenience methods.
- Stable contract
- Internal changes do not routinely force caller changes.
Important distinctions
- Large module
- Size alone is not depth; a large module with a large interface can still expose most of its complexity.
- Opaque code
- Information hiding preserves a clear contract and evidence, rather than concealing behavior that callers must understand.
Implementation signals
- Compare interface complexity with the capability it exposes
- Name modules in the domain language
- Test behavior at stable boundaries while retaining focused internal tests
Failure modes
- A shallow wrapper adds another concept without hiding complexity
- A general-purpose module becomes a dumping ground
- Hidden side effects violate the apparent contract
Sources and further study
- Stanford University — A Philosophy of Software Design, Second Edition
The author’s official book page identifies deep, general-purpose modules and separation of important from unimportant information as central software-design concerns.
Use in this library: Primary definition. This is the author’s book page rather than empirical evidence that module depth improves every codebase; application remains contextual and requires engineering judgment.
guidance · guidance · Published 2021-07 - AI Engineer — "Software Fundamentals Matter More Than Ever" — Matt Pocock
A conference talk arguing that shared language, deliberate software design, deep modules, and fast test feedback become more important as coding agents increase implementation throughput.
Use in this library: Practitioner perspective. This is an attributed practitioner argument illustrated with examples, not a controlled study showing that the proposed practices produce universal outcomes.
video · video · Published 2026-04-23 - AI Hero — Claude Code for Real Engineers
The official course page frames AI-assisted engineering around planning, decomposition, steering, feedback loops, tracer bullets, sandboxing, and maintaining navigable production codebases.
Use in this library: Practitioner perspective. This is a commercial course description and first-party outcomes narrative, not independent evidence of learner or production results; examples focus on Claude Code.
course · course · Published 2026-03-30