codebase-design

Apply the behavior-preserving inlining test: imagine inlining the module into every caller. If policy, sequencing, or error-handling knowledge spreads across callers, keep the module; if callers get simpler with no duplicated knowledge, the module is shallow and can be merged.

A deep module hides substantial coherent behavior and design decisions behind a small, stable caller-facing contract. Depth is measured by caller leverage and maintainer locality, not by lines of code, and the contract includes errors, ordering, effects, and performance obligations.

Create a seam only with concrete evidence: substitution needs, independent testing, volatility isolation, ownership, trust, runtime failure, or deployment boundaries. A production adapter plus a faithful test interactor can justify a seam; accidental wrappers do not.

No. Public HTTP contracts published or versioned across an ownership boundary are routed to the api-design skill. This Skill covers in-process module and package contracts, including ordinary component props.

Follow the deepening reference: fix the review target, establish behavior tests first, define the target contract, move one decision at a time, use temporary compatibility facades only when required, and retire old modules only after equivalent behavior coverage exists.

Depth without cohesion creates a god module. Do not consolidate code that evolves, fails, deploys, or is authorized independently, and do not diagnose intentionally thin edges like route leaves, adapters, or composition roots as shallow.