skills.rest
j172
j172COMMUNITY
Explore all skills by this author →
Website𝕏@j172GitHub

codebase-design

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

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

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, depth, seam, adapter, leverage, and locality so teams and AI agents name things consistently. - Dependency-aware deepening: Classify dependencies as in-process, local-substitutable, remote-but-owned, or true external, and choose the right seam and adapter strategy for each. - Design It Twice workflow: Spawn parallel sub-agents to produce radically different interface candidates, then compare them on depth, locality, and seam placement. - Use Case: When refactoring a cluster of shallow classes that wrap a database and a payment API, 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's interface using the deep-module vocabulary and suggest where to deepen it and place the seam.

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 so callers get more leverage per unit of interface they learn.

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

An interface is everything a caller must know to use a module, including invariants, ordering, and error modes. A seam is the location where that interface lives, a place where behaviour can be altered without editing in place.

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 and should be avoided.

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

Inject the external dependency as a port and provide a mock adapter in tests. Write tests at the deepened module's interface, assert on observable outcomes, and delete old shallow-module unit tests.

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

Depth is a property of the interface, not implementation size, so padding an implementation does not help. Modules with genuinely varying caller needs may resist a small interface, and premature seams add indirection without payoff.

Related Skills

Explore More Software Engineering Skills→
gaborbencsikgaborbencsik

improve-codebase-architecture

Identify shallow modules and leaky seams to propose refactoring deepening opportunities.

Community
Advanced
kashman001kashman001

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
AlteriomAlteriom

prd-to-ddd-design

Convert PRDs into DDD models with bounded contexts, aggregates, and domain events.

Official
Advanced