---
name: principle-deep-modules
description: "Apply when decomposing a system, adding a module, or assigning parallel agent work. Wide at the system level, deep at the module level, shallow in directory nesting: each module hides substantial functionality behind a small public entry point, and agents coordinate through contracts, not shared internals."
disable-model-invocation: true
---

# Deep Modules

Build a wide system of deep modules. Each module encapsulates substantial functionality behind a small, stable interface. The system holds several independently owned modules that agents can work on in parallel.

**Why:** Agents reason best within a bounded context: inputs, contract, outputs, without loading adjacent internals. Deep modules lower context requirements, constrain what a change can accidentally break, let multiple agents modify separate modules without editing shared internals, and make review a check against a contract. A shallow module exposes many functions, types, and implementation decisions relative to the value it provides, and every consumer inherits them.

**The topology:**

- Wide at the system level. Several independently understandable modules, not one giant deep module hiding the whole application.
- Deep at the module level. A small public API over significant internal implementation. Depth is the ratio of functionality hidden to interface exposed. The interface-compression test in the **minimize-reader-load** principle skill is the arbiter, so a pass-through entry point that re-exports three functions is not depth.
- Shallow in directory nesting. Deep conceptual modules, shallow paths. `src/ordering/domain/` is fine; `src/modules/business/order/core/domain/entities/internal/` is not.

**The rules:**

- One obvious public entry point per module. Internal accessibility does not imply architectural permission; callers never reach through to another module's internals.
- Feature-oriented organization over layer-oriented. Implementing one behavior should read a small, predictable portion of the repository, not edits across six distant layer directories. This is the **guard-the-context-window** principle skill applied to repo layout.
- Unidirectional dependencies, enforced by a mechanism where feasible (the **encode-lessons-in-structure** principle skill). Circularity forces global reasoning.
- Minimal shared utility layers. A generic helpers module becomes an uncontrolled coupling point. Prefer local duplication until the shared concept has the same semantics, lifecycle, ownership, and reasons to change.
- Assign parallel agent work by module ownership: one agent owns a complete vertical behavior, and agents coordinate through contracts. One-agent-per-layer forces continuous coordination for a single behavior. This is the **separate-before-serializing-shared-state** principle skill at architecture scale.

**When wider interfaces are appropriate:** inherently compositional domains, such as collection utilities, AST manipulation, UI component libraries, query builders, and SDK bindings. Organize the surface into coherent namespaces even then.

Each module's public surface follows the **design-the-surface** principle skill. [About deep modules](../../docs/explanation/about-deep-modules.md) grounds the topology and the agent-facing reasons for it. Skills like `codebase-design` ground the vocabulary further when installed.