skills.rest
1arley
1arleyCOMMUNITY
Explore all skills by this author →
GitHub

codebase-design

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

Updated Aug 29, 2026
Search Tags:#refactoring#testability#software architecture#module design#interface#ports and adapters#seam
One-click install
npx skills add https://github.com/1arley/volibear --skill codebase-design-1arley
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/1arley/volibear/tree/main/.agents/skills/codebase-design
Command: npx skills add https://github.com/1arley/volibear --skill codebase-design-1arley

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 so interfaces stay small while behaviour concentrates behind clean seams. ## Core Features & Use Cases - Deep-module vocabulary: Precise definitions of module, interface, seam, adapter, depth, leverage, and locality so teams and AI agents name things consistently. - Dependency-aware deepening: Classifies dependencies as in-process, local-substitutable, remote-but-owned, or true external, and prescribes ports-and-adapters or mock strategies for each. - Design It Twice workflow: Spawns parallel sub-agents to produce radically different interface designs, then compares them on depth, locality, and seam placement. - Use Case: When refactoring a cluster of shallow service classes, use this Skill to decide where the seam goes, define a port with production and in-memory adapters, and rewrite tests against the new deep interface. ## Quick Start Ask the AI 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 puts a large amount of behaviour behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside the implementation. Measure depth as leverage: how much behaviour callers get per unit of interface they must learn.

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

A seam is the location where a module's interface lives, a place where behaviour can be altered without editing that code. 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 a production adapter and a test adapter. One adapter means a hypothetical seam that adds indirection without value; two adapters make the seam real.

How do I test a deepened module with external dependencies?▼

Classify the dependency first. In-process and local-substitutable dependencies need no port. Remote-but-owned services get a port with an in-memory test adapter, and true third-party services get a mock adapter injected through the interface.

Should I keep old unit tests after deepening modules?▼

No. Replace, don't layer: delete old unit tests on shallow modules once tests exist at the deepened module's interface. The interface is the test surface, and tests should assert observable outcomes that survive internal refactors.

Related Skills

Explore More Software Engineering Skills→
ronniepinnellronniepinnell

improve-codebase-architecture

Identify shallow modules and produce RFC-style refactor plans with cluster mapping.

Community
Advanced
ishandutta2007ishandutta2007
13

Improve Codebase Architecture

Identify shallow modules and propose deepening refactors using the deletion test.

Community
Intermediate
Cobalt-MoneyCobalt-Money
7

improve-codebase-architecture

Identify shallow modules and refactor them into deep, high-leverage interfaces.

Official
Advanced
kiminmonacokiminmonaco
7

improvement

Guide TDD-based improvements to existing ClaudeBar functionality.

Community
Advanced