Agent skill · shipshitdev
codebase-design
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
What it needs
About 3k tokens when loaded.
What this skill does
Codebase Design Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone. This is the design language. tech-debt and codebase-advisor inventory; structural-review judges a diff; this skill names the shape. Contract Inputs: A module, interface, or cluster being designed or restructured Outputs: Design decisions expressed in the glossary below Optional alternative interfaces via references/DESIGN-IT-TWICE.md Creates/Modifies: None by default. Calling skills apply the design. External Side Effects: None Confirmation Required: None. Advisory vocabulary and design process. Delegates To: None. tdd, structural-review, and codebase-advisor speak this vocabulary. Glossary Use these terms exactly — do not substitute "component," "service," "API," or "boundary." Consistent language is the whole point. Module — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service. Interface — everything a caller must know to use the module correctly: the type signature, plus invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature (too narrow — they refer only to the type-level surface). Implementation — what's inside a module, its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. Depth — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills shipshitdev/codebase-design