skills.rest
hareki
harekiCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

codebase-design

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

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

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 AI agents name things consistently. - Dependency-aware deepening: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes ports-and-adapters strategies for each, with replace-don't-layer testing guidance. - Design It Twice workflow: Spawns parallel sub-agents to produce radically different interface designs, then compares them on depth, locality, and seam placement with an opinionated recommendation. - Use Case: When refactoring a cluster of shallow service classes, use this Skill to identify the right seam, define a port with production and in-memory test adapters, and rewrite tests against the new deep interface. ## Quick Start Ask the AI to review a module's interface using the codebase-design vocabulary and suggest how to deepen it given its dependencies.

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 must 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 an in-memory 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 unit tests on the shallow modules it replaced.

What are the limitations of the deep module approach?▼

Depth measured as implementation-lines to interface-lines rewards padding, so this Skill uses depth-as-leverage instead. Over-applying seams creates hypothetical abstractions, which is why the two-adapter rule gates seam introduction.

Related Skills

Explore More Software Engineering Skills→
raphaelmansraphaelmans

improve-codebase-architecture

Analyze codebases to surface architectural friction and generate deepening RFCs.

Community
Advanced
haryelramalhoharyelramalho

codebase-design

Design deep modules with small interfaces and clean seams for complex codebases.

Community
Intermediate
Ramprasad4121Ramprasad4121
1

audit-prep-assistant

Prepare codebases for security review with static analysis and documentation.

Community
Advanced
SlevoDevSlevoDev

V3 DDD Architecture

Decompose monolithic claude-flow v3 orchestrators into bounded contexts.

Official
Advanced