skills.rest
sndrgrdn
sndrgrdnCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

codebase-design

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

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

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: a lot of behaviour behind a small interface, placed at a clean seam. ## Core Features & Use Cases - Deep-module vocabulary: Precise definitions of module, interface, depth, seam, adapter, leverage, and locality so teams and AI agents name things consistently. - Dependency-aware deepening: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes ports-and-adapters or mock strategies for each, with replace-don't-layer testing guidance. - Design It Twice workflow: Spawns parallel sub-agents to produce radically different interface designs 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 decide where the seam goes, define a port with production and in-memory test adapters, and write tests at the new deep interface. ## Quick Start Ask the AI to review a module in your codebase and propose a deeper interface using the deep-module vocabulary, including where the seam should go and how it should be tested.

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 a caller gets 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 an in-memory test adapter. One adapter means a hypothetical seam, which is just indirection. 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 owned services get a port with an in-memory test adapter. True third-party services like Stripe are injected as ports and mocked in tests.

Should I keep old unit tests after deepening modules?▼

No. Old unit tests on shallow modules become waste once tests exist at the deepened module's interface. Delete them and write new tests at the interface, asserting observable outcomes rather than internal state so tests survive refactors.

Related Skills

Explore More Software Engineering Skills→
raphaelmansraphaelmans

improve-codebase-architecture

Analyze codebases to surface architectural friction and generate deepening RFCs.

Community
Advanced
AceCodePtAceCodePt

codebase-design

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

Community
Intermediate
Ramprasad4121Ramprasad4121
1

audit-prep-assistant

Prepare codebases for security review with static analysis and documentation.

Community
Advanced
Joel-barriosnuevoJoel-barriosnuevo

architecture-patterns

Design and refactor backend systems using Clean Architecture, Hexagonal Architecture, and Domain-Driven Design.

Community
Advanced