codebase-design

Provides shared vocabulary and principles for designing deep modules with small interfaces.

Updated Jun 21, 2026
One-click install
npx skills add https://github.com/NicolaeRotaru/ad-mycity --skill codebase-design-nicolaerotaru
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/NicolaeRotaru/ad-mycity/tree/main/.cursor/skills/codebase-design
Command: npx skills add https://github.com/NicolaeRotaru/ad-mycity --skill codebase-design-nicolaerotaru

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams lack a consistent language for discussing module design, leading to shallow abstractions, misplaced seams, and interfaces that are hard to test or navigate. This Skill establishes a precise shared vocabulary (module, interface, seam, adapter, depth, leverage, locality) so design discussions and refactors stay grounded in the same principles. ## Core Features & Use Cases - Deep-module vocabulary: Defines module, interface, implementation, seam, adapter, depth, leverage, and locality with explicit terms to avoid. - Design principles: Includes the deletion test, interface-as-test-surface, and the one-adapter-vs-two-adapters rule for deciding when a seam is real. - Testability guidance: Shows concrete TypeScript patterns for dependency injection, returning results instead of side effects, and minimizing interface surface area. - Use Case: When refactoring a tangled service layer, use this vocabulary to decide where the seam belongs, whether the module is deep enough to justify its interface, and how to make it testable through that interface. ## Quick Start Ask the AI to review a module's interface using the deep-module vocabulary and suggest where the seam should go.

Frequently Asked Questions about codebase-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is a deep module in software design?▼

A deep module packs a large amount of behavior behind a small interface, giving callers leverage and maintainers locality. A shallow module has an interface nearly as complex as its implementation and should be avoided.

How do I decide where to put a seam in my code?▼

A seam is the location where a module's interface lives, and placing it is its own design decision. Only introduce a seam when something actually varies across it: one adapter means a hypothetical seam, two adapters mean a real one.

How do I make a module more testable through its interface?▼

Accept dependencies as parameters instead of constructing them internally, return results instead of producing side effects, and keep the surface area small. Callers and tests should cross the same seam at the interface.

What is the difference between an interface and an implementation?▼

The interface is everything a caller must know to use the module: type signatures, invariants, ordering constraints, error modes, and performance characteristics. The implementation is the body of code inside, which callers never need to understand.

When should I not introduce a new abstraction layer?▼

Skip the seam when only one adapter exists and nothing varies across it, since that creates a hypothetical seam with no payoff. Apply the deletion test: if deleting the module makes complexity vanish rather than reappear across callers, it was a pass-through.