skills.rest
sanjanb
sanjanbCOMMUNITY
Explore all skills by this author →
GitHub

codebase-design

Designs deep modules with small interfaces placed at clean seams.

1|Updated Jul 23, 2026
Search Tags:#refactoring#testability#code architecture#module design#interface#ports and adapters#seam
One-click install
npx skills add https://github.com/sanjanb/my-agent-harness --skill codebase-design-sanjanb
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/sanjanb/my-agent-harness/tree/main/skills/mp-codebase-design
Command: npx skills add https://github.com/sanjanb/my-agent-harness --skill codebase-design-sanjanb

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 refactor. This Skill provides a shared vocabulary and design principles for creating deep modules that hide complexity behind small interfaces. ## Core Features & Use Cases - Deep-module vocabulary: Defines precise terms (module, interface, seam, adapter, depth, leverage, locality) so teams and AI agents discuss design consistently. - Dependency-aware deepening: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes ports-and-adapters strategies for each, with replace-don't-layer testing guidance. - Parallel interface exploration: Spawns multiple sub-agents to design radically different interfaces for a candidate module, then compares them on depth, locality, and seam placement. - Use Case: When refactoring a cluster of shallow service classes, use this Skill to identify the right seam, design a minimal interface, and write tests at that interface instead of layering mocks. ## 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 substantial behavior behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside. Ask whether deleting the module would make complexity vanish (pass-through) or reappear across callers (earning its keep).

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

A seam is the location where a module's interface lives, a place where behavior can be altered without editing that spot. The interface is everything a caller must know to use the module: types, invariants, ordering, error modes, and configuration.

When should I introduce a port and adapter?▼

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

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. Tests should assert observable outcomes through the interface and survive internal refactors.

What are the limitations of the deep-module approach?▼

Depth measured as implementation-lines to interface-lines rewards padding, so this Skill uses depth-as-leverage instead. Not every cluster should be deepened: in-process dependencies are always safe, but true external dependencies require mock adapters and injected ports.

Related Skills

Explore More Software Engineering Skills→
GregM1991GregM1991

codebase-design

Designs deep modules with small interfaces, clean seams, and testable adapters.

Community
Intermediate
kashman001kashman001

codebase-design

Designs deep modules with small interfaces, clean seams, and testable adapters.

Community
Intermediate
Base-AnaliticaBase-Analitica

test-driven-development

Enforces red-green-refactor test-driven development workflow before writing production code.

Official
Intermediate
JannaelJannael
16

architecture-patterns

Define and apply Clean Architecture, Hexagonal Architecture, and Domain-Driven Design patterns to backend systems.

Community
Advanced