Codebase Design: Deep Modules

What it does

The skill supplies a shared architecture vocabulary: module, interface, implementation, seam, adapter, depth, leverage and locality. An interface includes error modes, configuration and ordering constraints, not just a function signature. Depth means useful behavior behind a manageable surface, not a high line-count ratio. The source challenges pass-through abstractions with a deletion test and separates private testing seams from the external interface. Companion material covers dependency strategies and comparing radically different interface designs.

When to use it

• An order workflow exposes too many implementation steps to each caller.
• Tests break whenever private helpers move.
• A proposed adapter interface exists for only one implementation without a concrete variation.

Step-by-step workflow

1. Read the domain glossary and identify the caller’s actual task.
2. List everything callers must know, including invariants, failures and ordering.
3. Apply the deletion test to shallow wrappers and identify complexity worth hiding.
4. Classify dependencies and place the smallest useful seam, comparing alternative interfaces when needed.
5. Validate the design through usage examples and observable tests at the chosen interface.

Example request

Use codebase-design to examine our order-intake module. Show what the web handler and batch importer each need to know today. Include validation, duplicate submission and payment failure in the interface discussion. Compare a small task-oriented interface with the current sequence of helper calls. Explain what complexity disappears from callers, which dependencies vary and how tests cross the same seam. Propose the design before changing code.

Worked example

Imagine two callers that both normalize addresses, check duplicate orders and translate payment errors. A useful intake interface can own those decisions so the callers submit an order and receive a clear result. An interface that merely renames each helper adds little depth. A concrete design review should demonstrate a normal order and a duplicate submission at the same interface, then explain which internal reorganizations would leave those tests unchanged. External payments still require explicit error behavior and an appropriate test adapter.

What you get

An interface proposal with stated invariants, dependency choices, caller examples and a behavior-level validation surface.

How to evaluate the result

• Compare the knowledge required by callers before and after the proposal.
• Check error modes and ordering constraints as carefully as method counts.
• Confirm added seams have concrete variation and tests cover observable outcomes.

What you need

Relevant source code, real callers, known failure cases and project terminology. Alternative-design references require subagents if followed literally.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

This is design guidance rather than a mandate to create interfaces or merge every module. A smaller type signature can still hide confusing operational requirements. Tests and dependency substitutes must represent real failure modes; an in-memory adapter does not prove production transport reliability.

Related workflows

• Use improve-codebase-architecture to find a specific area worth redesigning.
• Use tdd after agreeing the interface and the behaviors that must survive refactoring.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license