Your Codebase Is the Biggest Prompt: Deep Modules Return, Interfaces for Humans, Implementation for AI
> A video script argued that "the biggest influence on AI output is not your prompt—it's your codebase," citing the deep module concept from *A Philosophy of Software Design*. Tracing it back leads to Matt Pocock's (Total TypeScript / AI Hero) article "How To Make Codebases AI Agents Love" (aihero.dev). This post audits the material, then connects it to the broader theme of interface costs—because it's really about the same question: what structure should cross the human-machine boundary.
1. Source Fidelity Check
Verifying the video summary against the original article:
| Video claim | Original text | Verdict | |---|---|---| | "The biggest influence on AI output isn't the prompt, it's the codebase" | "Your codebase, way more than your prompt or your AGENTS.md file, is the biggest influence on AI's output" | Accurate — the original also dismisses AGENTS.md | | Three costs: slow feedback / hard navigation / cognitive burnout | Poor feedback loops / Hard to navigate / Cognitive burnout | Accurate | | Like the protagonist of Memento | "like the guy from Memento stepping into your codebase" | Accurate, verbatim | | Deep modules come from *A Philosophy of Software Design* | "comes from A Philosophy of Software Design" | Accurate — Ousterhout 2018: simple interface hiding large implementation | | Gray-box modules: interface for yourself, implementation for AI | "You own the interface. AI owns the implementation. Tests keep it honest." | Accurate — the original adds a third clause the video omitted: tests as notary | | Only seven or eight chunks fit in your head | "seven or eight chunks" | Accurate | | AI is a new hire onboarded 20 times a day | "You're spawning 20+ new starters a day" | Accurate | | 20-year-old practices that work for humans also work for AI | "This is how good codebases have been designed for 20 years. What works for humans is also great for AI." | Accurate — but the most debatable sentence in the piece; see below | | Effect makes seamless modularity easy | "I've been using Effect more and more" | Caveat — Pocock is a prominent Effect evangelist; this is self-promotion, one option not the only solution |
Fidelity is unusually high—no number inflation, no honor inflation. Only flags: the Effect section (conflict of interest) and the AI Hero newsletter plug. The original also contains two hard items the video skipped: an /improve-codebase-architecture skill that lets an agent automatically audit and refactor a codebase toward the deep-module pattern—the article's prescription is already productized as a skill the agent itself can execute—and his workflow circulating on Reddit (GitHub Issues as a kanban board, narrow vertical slices).
2. Why the Codebase Outweighs the Prompt
In interface-cost terms: the prompt is a one-shot parameter; the codebase is the persistent interface. Every time you spawn a new agent, the prompt decides "what to do this time," while the codebase decides "what it can see, how fast it can move, and how long until it learns it's wrong." The former scopes to one session; the latter is the shared environment of all sessions. The three costs translate to:
- Slow feedback = a latency tax on verification bandwidth: AI keeps stacking changes on errors it can't detect
- Hard navigation = an interface tax on the context window: of the tokens flattened into the window, how many describe structure vs. noise
- Cognitive burnout = human verification bandwidth consumed by implementation details: you're patching the AI's missing context
- 20 years ago: complex implementation hidden behind an interface, users need not care
- 2026: complex implementation fenced off by an interface, AI writes it, you need not care
- Deep modules work for humans because working memory can't hold hundreds of modules—a cognitive bottleneck
- Deep modules work for AI because interface signatures are the highest information-density tokens in a context window: one function signature + type annotations carries a module's full callable semantics in a few dozen tokens, implementation retrieved on demand—context economics, i.e., interface-cost minimization
This is the same problem as structure loss at the model→corpus interface: when the codebase→model interface (files + type system) loses structure, navigation quality degrades. The codebase is the human-supplied persistent context interface for agents, and its structural quality directly prices the effective information density of every call.
3. Deep Modules' Second Spring: From "Hiding" to "Delegating"
Ousterhout (2018) defined deep modules as "large implementations hidden behind simple interfaces," criticizing shallow modules for transferring complexity to users. Pocock performs a semantic inversion in the agent era—"hiding" becomes "delegating":
The inversion requires tests: the interface locks behavior, tests lock the interface. The "gray-box module" is a three-way property split—interface is human property (boundary design = taste), implementation is AI property (token commodity), tests are the notary (assertion-execution separation). Taste isn't outsourced; it moves to the boundary.
The Memento metaphor upgrades well: the protagonist runs on external physical memory (tattoos, photos). LLMs have session-level amnesia plus codebase-level persistence—that's not a defect, it's memory architecture layering. The codebase is a curated external memory shared by humans and AI, predating agent-era constructs by two decades—only now discovered to have always been doing this job.
4. Where the Analogy Breaks: Same Conclusion, Different Mechanism
The smartest and vaguest sentence: what works for humans works for AI. The conclusion holds; the mechanisms differ:
The common assumption across approaches: structure should live in the code, not in context descriptions. Static files like AGENTS.md lose to the codebase because they are natural-language paraphrases *of* structure, while module boundaries *are* the structure.
Editorial Notes
The real contribution isn't "codebases matter" (already consensus in agent engineering circles) but framing the human-machine division as a property problem: interface to humans, implementation to AI, tests as notary. It's the cleanest engineering sample of verification-bandwidth economics: tests turn "reviewing AI-written code" into "running assertions," and humans spend bandwidth only at the boundary.
A counterpoint worth archiving: Ousterhout's deep modules were designed for humans. If models keep improving, the "deep" may stop being necessary—shallow interfaces with implementations chewed directly by long context is another possible collapse path. A falsifiable prediction: within 12 months, mainstream agent tools will make "module maps" a first-class citizen—agents auto-maintaining structured codebase maps (Pocock's /improve-codebase-architecture skill is the prototype). At that point, half the manual discipline in deep-module articles gets automated.
---
*Verification notes: original at aihero.dev/how-to-make-codebases-ai-agents-love; Ousterhout's deep-module definition cross-checked across multiple sources; parallel takes on jamescroft.co.uk and moderndescartes.com; Reddit r/vibecoding discussions of his workflow; Effect section flagged as conflicted interest.*
---
Next-step options: 1. Dissecting the /improve-codebase-architecture skill: read the skill's implementation in the mattpocock/skills repo to see the prompts and audit rules (GitHub direct fetch, ~20 min short review); 2. Measuring the interface tax in untyped languages: compare typed vs. untyped JS/TS open-source libraries running identical modification tasks, comparing token consumption and success rates (half-day empirical post); 3. Deep dive on the counterargument: will long context + unified memory flatten the necessity of deep modules—an analysis-only post on the "interface depth vs. context length" tradeoff.