Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

codebase-design

Use when designing or improving a module's interface (deep modules, small interfaces, clean seams) or finding and assessing shallow modules worth deleting, inlining or deepening. Moves -> refactoring-catalog.

coding-agent · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add rafaelob/pragmatic-agent-skills --skill codebase-design

About this skill


name: codebase-design description: "Use when designing or improving a module's interface (deep modules, small interfaces, clean seams) or finding and assessing shallow modules worth deleting, inlining or deepening. Moves -> refactoring-catalog." license: Apache-2.0 metadata: tags:

  • domain-expertise
  • codebase-design
  • deep-modules
  • ousterhout
  • module-design
  • seam
  • testability
  • interface-design version: "1.4.3" author: coding-agent category: domain-expertise subcategory: frameworks vendor: universal lifecycle: active coding_agent: true audience: developer output_format: markdown modality: text freshness: 2026-08 upstream: https://github.com/mattpocock/skills upstream_mode: adapted upstream_baseline_commit: 5b15a47f2d7150f545fbcacbfe381787fc0230dc upstream_baseline_date: 2026-08-21 upstream_author: Matt Pocock upstream_path: skills/engineering/codebase-design/SKILL.md adaptation_summary: 'Harness-neutral subagent dispatch (14bfbbd). Glossary location is left to local conventions. House Design Workflow and Checklist kept.' upstream_not_adopted: em-dash-sweep: Cosmetic 3216582; house keeps existing punctuation. Agent-tool: Cursor Task API; this catalog dispatches via the runtime in use.

Codebase Design — Deep Modules

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this vocabulary and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.

Glossary

Use these terms for the concepts below; they disambiguate "component," "service," "API," or "boundary" when those words are being used loosely for different things in the same discussion.

TermDefinitionAvoid
ModuleAnything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice.unit, component, service
InterfaceEverything a caller must know to use the module correctly: type signature, invariants, ordering constraints, error modes, required configuration, performance characteristics.API, signature (too narrow)
ImplementationWhat is inside a module. Distinct from Adapter: a Postgres repo is a small adapter with large implementation; an in-memory fake is a large adapter with small implementation.—
DepthLeverage at the interface: the amount of behaviour a caller or test can exercise per unit of interface they must learn. A module is deep when large behaviour sits behind a small interface; shallow when the interface is nearly as complex as the implementation.impl-lines / interface-lines ratio
SeamA place where behaviour can be altered without editing at that place (Feathers). The location at which a module's interface lives. Where to put the seam is its own design decision.boundary (overloaded with DDD bounded context)
AdapterA concrete thing that satisfies an interface at a seam. Describes role, not substance.—
LeverageWhat callers get from depth: more capability per unit of interface learned. One implementation pays back across N call sites and M tests.—
LocalityWhat maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place. Fix once, fixed everywhere.—

Deep vs Shallow

Deep module             Shallow module (avoid)
┌──────────────────┐    ┌──────────────────────────────┐
│  Small Interface │    │       Large Interface         │
├──────────────────┤    ├──────────────────────────────┤
│                  │    │   Thin Implementation         │
│ Deep Impl.       │    │   (mostly pass-through)       │
│                  │    └──────────────────────────────┘
└──────────────────┘

When designing an interface, ask:

  • Can I reduce the number of methods?
  • Can I simplify the parameters?
  • Can I hide more complexity inside?

Core Principles

Depth is a property of the interface, not the implementation. A deep module can be internally composed of many small, swappable parts — they just are not part of the external interface. A module can have internal seams (private to its implementation) as well as the external seam at its interface.

The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through and is earning nothing. If complexity reappears across N callers, it was earning its keep.

The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.

Two adapters are evidence of a real seam, not a requirement for one. A second adapter (typically production + test stand-in) proves something varies across the boundary, which is why it is the easiest justification to check. But it is one sufficient reason, not the only one. A seam is also justified by:

  • independent volatility — the two sides change for different reasons, on different cadences;
  • an external contract — the boundary is where a protocol, schema, or published API is honoured;
  • a security boundary — trust, authorization, or tenancy changes across it, and collapsing it would erase the place the check belongs.

What is not a justification is a seam added because a second implementation might appear someday. Absent one of the reasons above, the seam is speculative — the cost is real now and the variation is hypothetical.

Relationships

  • A Module has exactly one Interface — the surface it presents to callers and tests.
  • Depth is a property of a Module, measured against its Interface.
  • A Seam is where a Module's Interface lives.
  • An Adapter sits at a Seam and satisfies the Interface.
  • Depth produces Leverage for callers and Locality for maintainers.

Designin

Read the complete source ↗