# Design deep modules with clear interfaces

Most codebases suffer from shallow modules with large interfaces and thin implementations. This skill provides a shared vocabulary and methodology for designing deep modules, deciding where seams go, and making code more testable and maintainable.

## Install

```bash
npx skillstore add mattpocock/codebase-design
```

## Metadata

- - Slug: mattpocock-codebase-design
- - Version: 1.0.0
- - Author: mattpocock
- - GitHub username: mattpocock
- - License: MIT
- - Repository: https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design/
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: safe
- - Risk factors: external\_commands
- - Quality score: 80
- - Quality tier: silver
- - Public page: https://skillstore.pages.dev/skills/mattpocock-codebase-design
- - Manifest: https://skillstore.pages.dev/api/skills/mattpocock-codebase-design/manifest

## Capabilities

- Provides a precise vocabulary for module, interface, seam, adapter, depth, leverage, and locality
- Offers principles for designing interfaces with fewer methods and simpler parameters
- Includes a classification system for dependencies \(in-process, local-substitutable, remote but owned, true external\)
- Provides guidance on seam discipline including when to introduce ports and adapters
- Suggests testing strategies based on the replace-don't-layer principle
- Includes a parallel sub-agent pattern for exploring radically different interface designs

## Use Cases

- Designing a new module interface: A developer wants to design a clean interface for a new feature with maximum leverage for callers and minimum surface area for tests.
- Refactoring shallow modules into deep ones: An engineering team has accumulated shallow modules with thin implementations and wants to consolidate them into deeper, more testable units.
- Establishing shared architectural vocabulary: A team needs a consistent language for discussing module boundaries, seams, and adapters across code reviews and design discussions.

## Prompt Templates

### Review a module's interface for depth

```
Review the [module name] interface. Is it deep or shallow? Can I reduce the number of methods or simplify the parameters? What complexity could be hidden inside the implementation?
```

### Find deepening opportunities

```
Look at these [N] related shallow modules. Could merging them create a deeper module? Classify their dependencies as in-process, local-substitutable, remote-but-owned, or true external.
```

### Decide where to place a seam

```
I need to decide where the seam should go for [feature]. Apply the deletion test: if I delete this module, does complexity vanish or spread? Should there be a port or just an internal seam?
```

### Explore alternative interfaces in parallel

```
Spawn 3 sub-agents to design radically different interfaces for [module]. Agent 1 should minimize the interface, Agent 2 should maximize flexibility, and Agent 3 should optimize for the most common caller.
```

## Limitations

- Does not generate code or implement refactoring automatically
- Vocabulary is opinionated and may conflict with existing team terminology
- Requires human judgment to apply the deepening methodology to specific codebases
- Does not provide tools for static analysis or measurement of module depth

## Best Practices

- Use the exact vocabulary from this skill consistently across your team and documentation
- Apply the deletion test to verify a module is earning its keep
- Only introduce a port when at least two adapters are justified
- Write tests at the module's interface, not past it
- Design for two adapters \(production and test\) before adding more

## Anti Patterns

- Substituting 'component', 'service', 'API', or 'boundary' for the precise terms in this skill
- Introducing seams with only one adapter
- Testing past the interface by reaching into internal state
- Treating depth as a ratio of implementation-lines to interface-lines
- Keeping old unit tests on shallow modules after consolidation

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-24T09:18:14.356\+00:00
- - Summary: The codebase-design skill is a pure documentation skill providing vocabulary and methodology for designing deep modules. All 35 static findings are false positives: 'Weak cryptographic algorithm' detections are triggered by the word 'deep' \(confused with DES cipher references in unrelated codebases\), 'Ruby/shell backtick execution' matches markdown backtick formatting for code blocks, and 'System reconnaissance' is a misidentification of architectural vocabulary. No executable code, scripts, or data flows exist in any file.

## Stats

- - Views: 0
- - Downloads: 4
- - Favorites: 0
- - Popularity score: 0