Overview
A shallow-module codebase contains many small files that export small pieces of behavior and depend on one another in complex ways. To understand one change, the agent must traverse a broad dependency graph. Testing is also ambiguous:
- Should every tiny function have its own test boundary?
- Should neighboring files be mocked?
- Should a large group be tested together even though its public behavior is unclear?
Agents often respond by wrapping each small function in an isolated test. Those tests may prove that the pieces work separately while missing ordering errors, dependency interactions, or the behavior of the larger system.
A deep module exposes a small, stable interface while containing a large amount of implementation behind it. The caller interacts with a few clear operations. The module can be surrounded by a meaningful test boundary that covers substantial behavior.
This architecture supports a useful division of responsibility. The human designs the interface and understands the module's purpose, inputs, outputs, and behavior under important conditions. The agent can implement the internal details. The module becomes a gray box: its shape and guarantees are known, while every internal line does not have to remain in the human's working memory.
The module map should be considered during planning, not after the code is generated. A destination document can identify a new deep service, the interface it should expose, and the existing routes or services it will modify. The implementation issues then preserve that structure.
An architecture-improvement skill can scan the repository for clusters of tightly related modules, untested logic, and opportunities to deepen interfaces. It can explain why a set of functions is coupled and propose a larger unit that can be tested from the outside.