Deep modules in AI-augmented development

Deep modules in AI-augmented development: interface design, contract-first delegation, and architectural rescue of AI-generated codebases

2026-04-30 · agentic-ai ai-architecture tools-infrastructure software-engineering benchmarks-eval · medium · source → · wiki →

key claims

The available evidence for architecture benefit is indirect rather than head-to-head: foundational module theory, modern context-management guidance, and configuration studies converge on the same mechanism, but none of them quantifies a universal uplift multiplierMit (n.d.)Ousterhout (2018)Anthropic (2025)Santos et al. (2025)
Deep modules should improve AI codebase navigation and modification because they minimize the amount of design knowledge exposed across call sites, which lowers the context each change requires and keeps more reasoning inside a bounded implementation surfaceMit (n.d.)Ousterhout (2018)Anthropic (2025)
Current agent guidance and configuration practice repeatedly elevate architecture, context scope, and verification rules as operational concerns rather than as afterthoughts, which shows that these surfaces are treated as first-class configuration targets in real agent workflowsSantos et al. (2025)GitHub (2025)Anthropic (2025)
Public practitioner evidence directly shows that explicit interface cues such as return types and durable rule files are treated as aids to future AI assistants' understanding of code intent, which gives a concrete small-scale example of the broader deep-module argumentPocock (2025)Pocock (2025)
Contract-first delegation is the most defensible workflow pattern because it combines architecture, explicit types, tests, and repository instruction artifacts while preserving human ownership of contracts and verification, even though the pattern is better supported as a synthesis than as a named experimental methodPocock (2025)Anthropic (2025)GitHub (2025)Mitchell (2026)
Bounded-task AI coding can be genuinely useful, but weaker human scrutiny and fragile multi-step reasoning make architecture and verifier boundaries more important than raw suggestion quality alone when changes must remain coherent across a codebaseGitHub (2024)Dakhel et al. (2023)Welter et al. (2025)
Rescue of a densely coupled codebase with weak boundaries is feasible through iterative refactoring, hotspot prioritization, persistent context, and small validated batches, and the available evidence favors that path over blind whole-repository rewritesFowler (2018)CodeScene (2021)CodeScene (2021)Atlassian (2025)
The payoff from rescue is front-loaded on active hotspots and interface seams, while the cost rises as hidden coupling and declining code health accumulate, so no single effort-benefit ratio is portable across codebasesAtlassian (2025)Mitchell (2026)CodeScene (2021)

Research Question

How much more effective is Artificial Intelligence (AI) at understanding, navigating, and correctly modifying a codebase composed of deep modules with simple interfaces versus one filled with many shallow modules, and can iterative architectural improvement rescue an AI-generated "ball of mud" codebase, and if so what is the typical effort-versus-benefit ratio?

Findings

Executive Summary

Indirect evidence suggests Artificial Intelligence (AI) coding agents should be more reliable in codebases organized around deep modules with explicit interfaces than in shallow, densely coupled codebases, but the gain appears to come from a bundle of controls that also includes verifier strength, type information, tests, and repository instruction artifacts rather than from module depth alone.

The best-supported delegation pattern keeps humans responsible for contract design and verification while letting the AI search within that boundary for a working implementation, which makes module depth one enabling condition among several rather than the sole cause of safer outcomes.

A densely coupled codebase with weak boundaries can be rescued incrementally, but the credible path is hotspot-first and batch-validated rather than a one-shot rewrite.

The effort-versus-benefit ratio is therefore highly uneven: targeted architectural work on high-churn boundaries can produce meaningful gains, while whole-repository rescue becomes more expensive as hidden coupling, duplication, and code-health decline accumulate.

Key Findings

The available evidence for architecture benefit is indirect rather than head-to-head: foundational module theory, modern context-management guidance, and configuration studies converge on the same mechanism, but none of them quantifies a universal uplift multiplier.
Deep modules should improve AI codebase navigation and modification because they minimize the amount of design knowledge exposed across call sites, which lowers the context each change requires and keeps more reasoning inside a bounded implementation surface.
Current agent guidance and configuration practice repeatedly elevate architecture, context scope, and verification rules as operational concerns rather than as afterthoughts, which shows that these surfaces are treated as first-class configuration targets in real agent workflows.
Public practitioner evidence directly shows that explicit interface cues such as return types and durable rule files are treated as aids to future AI assistants' understanding of code intent, which gives a concrete small-scale example of the broader deep-module argument.
Contract-first delegation is the most defensible workflow pattern because it combines architecture, explicit types, tests, and repository instruction artifacts while preserving human ownership of contracts and verification, even though the pattern is better supported as a synthesis than as a named experimental method.
Bounded-task AI coding can be genuinely useful, but weaker human scrutiny and fragile multi-step reasoning make architecture and verifier boundaries more important than raw suggestion quality alone when changes must remain coherent across a codebase.
Rescue of a densely coupled codebase with weak boundaries is feasible through iterative refactoring, hotspot prioritization, persistent context, and small validated batches, and the available evidence favors that path over blind whole-repository rewrites.
The payoff from rescue is front-loaded on active hotspots and interface seams, while the cost rises as hidden coupling and declining code health accumulate, so no single effort-benefit ratio is portable across codebases.

Assumptions

Interface-first guidance from TypeScript-centric sources is relevant to broader software engineering because the claimed mechanism is explicit contract surface rather than language choice alone.
Atlassian's feature-gate cleanup case is relevant to AI-generated-code rescue even though the target code was not described as wholly AI-generated, because the case still shows what large-scale, context-rich architectural cleanup requires in practice.
The absence of a direct benchmark in the accessible search is an evidence gap rather than proof that architecture does not matter.

Analysis

The core analytic move is to combine a strong theoretical mechanism with modern agent constraints: information hiding reduces externally required knowledge, and context limits make externally required knowledge the scarce resource for AI agents.

The public AI-era evidence is stronger on design and workflow convergence than on causal measurement, which is why this item can recommend deep modules and contract-first delegation directionally without pretending the uplift is already numerically pinned down.

A rival explanation is that verifier strength, test coverage, type information, naming and specification artifacts, and repository instructions drive most of the observed gain regardless of module depth.

The evidence partly supports that rival explanation, which is why the strongest conclusion here is not that architecture dominates those controls, but that deep modules make them more local, legible, and enforceable inside real maintenance tasks.

Rescue economics favor modular cleanup, namely identifying active seams, restoring boundaries, and iterating with tests and history-based metrics, because that is where current evidence ties effort to observable benefit.

Risks, Gaps, and Uncertainties

The sources reviewed here do not provide a direct controlled study that compares otherwise similar deep-module and shallow-module codebases under the same AI task.
The strongest public evidence for contract-first delegation is practitioner guidance rather than controlled experimentation.
The best rescue case in this item is a single detailed practitioner report rather than a multi-organization benchmark.
Any whole-repository effort curve remains uncertain because rescue cost depends heavily on hidden coupling, hotspot distribution, and how much executable verification already exists.

Open Questions

What measurable proxy for module depth best predicts agent success on multi-file maintenance tasks?
Can a controlled study randomize the same repository into deep-boundary and shallow-boundary variants to estimate the architecture effect on agent accuracy and context consumption directly?
Which hotspot-first rescue sequence gives the best return in real AI-heavy codebases: interface extraction, dependency inversion, module consolidation, or test-harness reinforcement?