codebase-design

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

Updated May 11, 2026
One-click install
npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill codebase-design-cloudofgeorge
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/cloudofgeorge/AI-hands-Engineer/tree/main/skills/engineering/codebase-design
Command: npx skills add https://github.com/cloudofgeorge/AI-hands-Engineer --skill codebase-design-cloudofgeorge

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 that hide complexity behind small interfaces. ## Core Features & Use Cases - Deep module vocabulary: Precise definitions of module, interface, seam, adapter, depth, leverage, and locality so teams and agents name architectural concepts consistently. - Dependency-aware deepening: Classifies dependencies as in-process, local-substitutable, remote-but-owned, or true external, and prescribes ports-and-adapters strategies for each. - 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, merge the cluster into one deep module, and write tests at the new interface instead of the old internals. ## Quick Start Ask the agent to review a module or package 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?

Start by reducing the number of methods, simplifying parameters, and hiding more complexity inside the implementation. A deep module gives callers large amounts of behavior per unit of interface they must learn, and tests are written at that interface rather than against internals.

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 in place. The interface is everything a caller must know to use the module, including invariants, ordering, error modes, and performance characteristics.

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. A single-adapter seam is just indirection; one adapter means a hypothetical seam, two adapters mean a real one.

How do I test a deepened module with external dependencies?

Classify the dependency first: in-process code needs no adapter, local-substitutable dependencies use stand-ins like PGLite, owned remote services get an in-memory adapter behind a port, and third-party services get a mock adapter. Write tests at the deepened module's interface and delete old shallow-module unit tests.

When should I not deepen a module?

Avoid deepening when the module is a genuine pass-through that fails the deletion test, meaning deleting it would not push complexity back into callers. Also avoid introducing seams where nothing actually varies across them.