Codebase Design

Codebase Design

Design coherent deep modules: substantial, related behavior and design decisions hidden behind a small, stable caller-facing contract. Optimize for leverage for callers and locality for maintainers without creating a god module.

Use this skill for logical responsibility and contract shape. Use structure-codebase for physical paths, packages, exports, dependency direction, enforcement, and folder migration. Use reduce-system-complexity when the selected objective is an evidence-backed net-reduction claim over whole-path mechanism rather than a deeper contract. Use evaluate-existing-solutions for a consequential unresolved library, tool, application, service, framework, or platform choice.

When improve-codebase-architecture loads this skill during an unselected audit, use only its vocabulary, principles, evidence tests, and thin-edge safeguards. Do not run the contract-design workflow or propose an exact interface until the user selects a candidate.

Read the relevant reference before proposing a consequential design:

• Read references/deepening.md when consolidating existing modules, classifying dependencies, or planning a safe deepening migration.
• Read references/design-it-twice.md when a new or changed contract is expensive to reverse or several credible shapes exist.
• Read references/source-notes.md when explaining provenance or comparing this adaptation with its sources.

Vocabulary

Use these terms to disambiguate, not to erase useful established vocabulary. API, component, service, signature, boundary, port, and bounded context remain valid when they name those specific concepts.

Design Principles

Hide decisions, not merely code

Place a responsibility behind a module when callers should not each know its policy, sequencing, representation, error recovery, or provider mechanics. A private helper extraction does not deepen a module if the same knowledge still leaks through its parameters and call order.

Keep depth cohesive

A tiny contract over an incoherent implementation is a god module, not a good deep module. Combine behavior only when it shares meaning, invariants, ownership, lifecycle, or a real axis of change. Preserve separate modules when they evolve, fail, deploy, or authorize independently. An extraction earns its boundary when the reader can name the decision or responsibility it owns and understand the caller with less cross-file reconstruction; a file per helper or a chain of trivial forwarding functions does not establish ownership.

Apply the behavior-preserving inlining test

Imagine inlining the module into every caller while preserving behavior:

• If policy, sequencing, error handling, or representation knowledge spreads across callers, the module earns its place.
• If callers become simpler because a pass-through disappears and no knowledge is duplicated, the module is shallow or misplaced.

This is the useful form of the deletion test. Do not imagine deleting the behavior itself.

Pull complexity downward deliberately

Make the common call simple. Accept complexity inside the implementation when doing so removes configuration, ordering, special cases, or provider knowledge from callers. Keep effects, failure modes, resource ownership, and performance costs explicit enough that callers can use the module safely.

Justify seams with evidence

Create a seam for a concrete need: substitution, independent testing, volatility isolation, ownership, trust, runtime failure, or deployment. Adapter count is evidence, not a rule. A production adapter plus a faithful test interactor may justify a seam; two accidental wrappers do not.

Test at the stable contract

Make caller-observable behavior the primary test surface. Do not export private helpers or expose internal seams solely to test them. A private subsystem may have focused tests when it is itself a coherent module or when an algorithm needs precise failure localization; those tests must not freeze incidental orchestration.

Preserve intentionally thin edges

Do not diagnose a route leaf, CLI command, adapter, generated client, or composition root as shallow merely because it is thin. Translation and wiring should often be thin. Judge whether policy is hidden in the correct inside module and whether the edge leaks provider or transport knowledge across its contract.

Workflow

1. Define the job and callers

State the behavior the module owns, its current and expected callers, the common case, and what must remain outside. Read project instructions, architecture decisions, glossary conventions, and relevant tests before naming anything new.

2. Inventory the full contract burden

List what each caller must know today:

• operations and data shapes;
• invariants and preconditions;
• call ordering and lifecycle;
• configuration and dependency construction;
• errors, retries, partial failure, and effects;
• latency, throughput, consistency, and transaction expectations.

Do not confuse a short type signature with a small interface.