Deep modules make a codebase explorable and testable for agents

An AI-friendly codebase is a few large modules with simple interfaces, not many small ones. Ousterhout’s “deep modules” hide a lot of implementation behind a narrow surface; a codebase of shallow modules forces the agent to hop between dozens of tiny blobs, and it often “doesn’t maybe get to the right module in time” or grasp the dependencies¹. The same structure that suits human comprehension also determines whether an agent can navigate the code at all.

Deep modules are also what make a codebase testable, because you verify at the interface and treat the interior as a gray box. That boundary is the leverage point: design the interface yourself, delegate the implementation to the agent, and review by testing the outside rather than reading every line inside¹. This is the structural cure for both shallow-module sprawl, which starves the agent of context (see: repo maps let agents navigate large codebases), and the cognitive exhaustion of reviewing every AI-written line — you only need to hold the interface map in your head, and that map belongs in the project’s shared vocabulary (see: shared organizational context is the real limit).