codebase-design

Designs deep modules with small interfaces placed at clean, testable seams.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/Fatih0234/mattpocock-skills-pi --skill codebase-design-fatih0234
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/Fatih0234/mattpocock-skills-pi/tree/main/skills/engineering/codebase-design
Command: npx skills add https://github.com/Fatih0234/mattpocock-skills-pi --skill codebase-design-fatih0234

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test, navigate, and change. This Skill provides a shared vocabulary and decision framework for designing deep modules, choosing where seams go, and safely deepening clusters of coupled code. ## Core Features & Use Cases - Deep-module vocabulary: Precise definitions of module, interface, seam, adapter, depth, leverage, and locality so teams and AI agents use consistent design language. - Dependency-aware deepening: Classifies dependencies as in-process, local-substitutable, remote-but-owned, or true external, and prescribes ports-and-adapters or mock strategies per category. - Parallel interface exploration: Dispatches isolated designer agents to produce radically different interface designs, then compares them on depth, locality, testability, and seam placement. - Use Case: When refactoring a tangle of small service classes, use this Skill to identify a deepening candidate, define a port at the seam with HTTP and in-memory adapters, and rewrite tests against the new interface. ## Quick Start Ask the agent to review a module in your codebase and propose a deeper interface using the codebase-design vocabulary.

Frequently Asked Questions about codebase-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a deep module interface?▼

A deep module hides a large amount of behavior behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside. Accept dependencies as parameters and return results rather than producing side effects so the interface doubles as the test surface.

What is the difference between a seam and an interface?▼

An interface is everything a caller must know to use a module, including invariants, ordering, and error modes. A seam is the location where that interface lives, a place where behavior can be altered without editing in place. Choosing seam placement is a separate design decision.

When should I introduce a port and adapter?▼

Introduce a port only when at least two adapters are justified, typically a production adapter and a test adapter. One adapter means a hypothetical seam and is just indirection. Use ports for remote-but-owned services and true external dependencies like third-party APIs.

How do I test a deepened module?▼

Write tests at the deepened module's interface, which is the test surface, and delete old unit tests on the shallow modules it absorbed. Tests should assert observable outcomes through the interface so they survive internal refactors.

What dependencies can be deepened into a module?▼

In-process dependencies can always be merged. Local-substitutable dependencies like PGLite or in-memory filesystems can be deepened when a test stand-in exists. Remote owned services need ports and adapters, while third-party services are injected as ports with mock adapters in tests.