← narwal.one/Second Brain
SecondBrain
Ask the Brain
Index/Conceptupdated Tue Jul 07 2026 08:00:00 GMT+0800 (Philippine Standard Time)

Deep Modules

architecturesoftware-designai-codingousterhoutmodulesinterface-design

Deep Modules

John Ousterhout's Philosophy of Software Design frame: a lot of functionality behind a small, simple interface. The opposite is a shallow module — small functionality, wide/complex interface.

The visual

Pocock in Software Fundamentals Matter More Than Ever (Matt Pocock, AI Engineer) draws the same code twice:

  • Shallow-module codebase: many tiny blobs, complex interconnects the agent has to walk through and reason about at every step. AI creates codebases like this by default.
  • Deep-module codebase: the same code, wrapped into a smaller number of large modules with simple interfaces exposed on top.

Why it matters more under AI

Two effects Pocock names, both in the AI-coding context:

  1. Deep modules are testable. The interface is small; a boundary test verifies the module's contract without spelunking through internals. That gives TDD-mode agents the fast, cheap feedback loop the Pragmatic Programmer "rate of feedback is your speed limit" line demands.
  2. Deep modules save your brain. When the module surface is small enough to hold in your head, you can treat the interior as a gray box: design the interface, delegate the implementation. Not for everything (Pocock's exceptions: finance, safety-critical), but for most modules. This is the practical form of "design the interface, delegate the implementation."

The failure mode of shallow-module codebases under AI: the agent can't hold the map. It tries to explore, misses the right module, misreads the dependencies, produces plausible-but-wrong changes. Deep modules bound the blast radius of each change to what the interface exposes.

Relation to other vault concepts

  • Verification Tax — deep modules pay down verification cost by shrinking the surface the human has to check. The vault's "10× harder to verify than to write" line loses force when the interface is 5 functions with narrow types.
  • Ubiquitous Language — the module names are part of the shared vocabulary. Deep modules and DDD's ubiquitous language reinforce each other: named boundaries with named contracts.
  • Skill Checklist — the same author's skills-side analog: keep SKILL.md minimal, put reference material behind context pointers. Deep-module code and small-SKILL.md skills are the same discipline at two scales.
  • Code Is Free — implementation being cheap is what makes deep modules practical: the extra effort to design a clean interface is worth it because the interior can be regenerated when needed.
  • Higher-Order Thinking — deep-module design is a higher-order-thinking activity (relationships, boundaries, contracts). Writing the module interior is lower-order and now cheap. The value is in the interface work.

The Pocock skill

improve-codebase-architecture — his reusable-steps skill for turning shallow-module sprawl into deep modules. Steps: explore, find related-code clusters, wrap each cluster in a deep module. Not one-shot; iterative.

Cross-links

Source