skills.rest
tlipoca9
tlipoca9COMMUNITY
Explore all skills by this author →
GitHub

codebase-design

Designs deep modules with small interfaces placed at clean seams.

Updated Feb 22, 2024
Search Tags:#refactoring#testability#software architecture#interface design#module design#ports and adapters#seams
One-click install
npx skills add https://github.com/tlipoca9/dotfiles --skill codebase-design-tlipoca9
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/tlipoca9/dotfiles/tree/main/home/dot_agents/skills/codebase-design
Command: npx skills add https://github.com/tlipoca9/dotfiles --skill codebase-design-tlipoca9

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 them. ## Core Features & Use Cases - Deep-module vocabulary: Defines module, interface, seam, adapter, depth, leverage, and locality with rejected framings 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 per category. - Design It Twice workflow: Spawns parallel sub-agents to produce radically different interface proposals, 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 interface. ## Quick Start Ask the AI to review a module's interface using the codebase-design vocabulary and propose a deeper design with a clear seam and adapter strategy.

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. Measure depth as leverage: how much behaviour a caller exercises per unit of interface they must learn.

What is a seam in software design?▼

A seam, from Michael Feathers, is a place where you can alter behaviour without editing in that place; it is the location where a module's interface lives. Choosing where the seam goes is a design decision distinct from what implementation sits behind it.

When should I use ports and adapters for dependencies?▼

Use ports and adapters when a dependency crosses a network boundary you own, such as microservices or internal APIs. Define a port at the seam, inject an HTTP or gRPC adapter in production, and use an in-memory adapter in tests.

When should I not introduce a seam or port?▼

Do not introduce a port unless at least two adapters are justified, typically production plus test. One adapter means a hypothetical seam; a single-adapter seam is just indirection that adds interface complexity without earning leverage.

How do I test a deepened module?▼

Write tests at the deepened module's interface, since the interface is the test surface. Delete old unit tests on the shallow modules, assert on observable outcomes through the interface, and use stand-ins or mock adapters for external dependencies.

Related Skills

Explore More Software Engineering Skills→
raphaelmansraphaelmans

improve-codebase-architecture

Analyze codebases to surface architectural friction and generate deepening RFCs.

Community
Advanced
kashman001kashman001

codebase-design

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

Community
Intermediate
JeromyJSmithJeromyJSmith
3

improve-codebase-architecture

Identify shallow modules and propose interface-focused refactoring candidates.

Community
Advanced
crgarcia12crgarcia12

rewrite-planner

Plan incremental component rewrites using the strangler fig pattern.

Community
Advanced