Codebase Design

Use for code-level module design, deep modules, interfaces, seams, adapters, testability, refactoring shallow modules, and finding architecture improvements in an existing codebase.

9 stars 2 forksSoftware Development Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add eralmansouri/skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add eralmansouri/skills --skill codebase-design
Manual install
git clone --depth 1 https://github.com/eralmansouri/skills.git /tmp/skills
mkdir -p ~/.claude/skills
cp -r /tmp/skills/skills/codebase-design ~/.claude/skills/codebase-design

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Codebase Design

Design deep modules: a lot of behavior behind a small interface, placed at a
seam where something actually varies, and tested through that interface. Depth
gives callers leverage and maintainers locality.

## Vocabulary

Use these terms consistently. Reserve *boundary* for bounded contexts and
service ownership; at code level, say *seam*.

- Module: anything with an interface and an implementation, at any scale: function, class, package, or vertical slice.
- Interface: everything a caller must know to use the module correctly: signature, invariants, ordering, error modes, configuration, and performance characteristics.
- Depth: behavior a caller or test can exercise per unit of interface learned. A shallow module's interface is nearly as complex as its implementation.
- Seam: a place where behavior can change without editing that place; where an interface lives.
- Adapter: a concrete implementation filling a seam, such as a Postgres store or an in-memory fake.
- Leverage: what callers gain from depth. One implementation pays back across every call site and test.
- Locality: what maintainers gain from depth. Change, bugs, and verification concentrate in one place.

## Principles

- Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it earns its keep.
- The interface is the test surface. Callers and tests cross the same seam; needing to test past it signals the wrong shape.
Read the full skill on GitHub

Details

Skill name
codebase-design
Path
skills/codebase-design/SKILL.md
Repo updated
15 October 2026

FAQ

What does the Codebase Design skill do?

Use for code-level module design, deep modules, interfaces, seams, adapters, testability, refactoring shallow modules, and finding architecture improvements in an existing codebase.

How do I install the Codebase Design skill?

Claude Code plugin: /plugin marketplace add eralmansouri/skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Codebase Design popular?

It lives in eralmansouri/skills, which has 9 GitHub stars and 2 forks.

Related skills

Design Review

9

eralmansouri/skills

Design review of a codebase area, branch, or PR. Maps its bounded contexts, vertical slices, and modules, then judges where rules live and whether flexibility sits where change actually happens. Use when the user asks for a design or architecture review, or when a review should judge structure rather than bugs or style.

Git & Code Review

Domain Driven Design

9

eralmansouri/skills

Use for domain-driven design, domain modeling, ubiquitous language, bounded contexts, aggregates, invariants, entities, value objects, domain services, domain events, and deciding whether a rich domain model is warranted.

AI, LLMs & Agents

Event Driven Systems

9

eralmansouri/skills

Use for event-driven or message-driven architecture, commands and events, queues, pub/sub, Kafka, choreography, orchestration, sagas, outbox, idempotency, retries, ordering, backpressure, consumer lag, and messaging operations.

Software Development

Computer Use CLI

9

TwillAI/skills

Automate and test Linux desktop apps (Electron, Tauri, React Native Desktop) in an X11 session using CLI commands for screenshot + mouse + keyboard. Includes coordinate scaling so you can click/type based on a smaller “API-sized” screenshot.

Software Development

Code Step Author

9

duvoai/skills

Answer questions about writing the Python program of a Duvo code step and the `duvo` SDK it calls. Use when the user asks how a code step reads its case, claims or settles work on a Queue, reaches a Connection, reads Policy values or attached files, what `duvo.execution` holds, which errors the SDK raises, or wants a snippet for a code step. Grounds every answer in the SDK surface that actually ships into the sandbox, and hands the writing of the program itself to the step's own AI generation rather than pasting code the user must transcribe.

Software Development

Context Engineering

9

claudekit/skillmark

Check context usage limits, monitor time remaining, optimize token consumption, debug context failures. Use when asking about context percentage, rate limits, usage warnings, context optimization, agent architectures, memory systems.

Software Development

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.