About codebase-design
A software design skill for structuring code around clear module boundaries and explicit request flows. It guides developers in assigning behavior to handlers, services, repositories, and adapters while avoiding unnecessary layers.
Key features
- 01Separate handlers, services, and repositories
- 02Keep external systems behind adapters
- 03Place rules at natural shared entry points
- 04Prefer explicit flows over hidden behavior
- 05Remove speculative layers and unused configuration
Use cases
- 01Plan ownership of behavior during a code change
- 02Review whether a proposed module boundary is useful
- 03Simplify layers that do not vary or add value
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/codebase-designin Claude Code to confirm it loaded.
Bundled filesagents/openai.yaml
Details
From the project READMECodebase Design
Prefer deep modules: useful behaviour behind a small interface at a clean seam.
Default flow
Handler → Service → Repository. Handlers translate protocol concerns (thin). Services own business rules and orchestration. Repositories own persistence only. Adapters isolate external systems.
Rules
- Preserve existing boundaries unless the change is explicitly about moving them.
- Put a rule where all callers naturally pass through it.
- Prefer explicit request flow over hidden magic.
- Delete speculative layers, single-use interfaces, and config for values that never vary.
- Name domain concepts with words from
CONTEXT.mdwhen the repo has one.
Completion: each changed behavior has one natural owner, callers cross the intended seam, and the resulting boundary is easier to test than the old one.