# Codebase Design

> Design deep modules and clean seams.

- Skill: `darknesskiller/codebase-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add darknesskiller/codebase-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/darknesskiller/codebase-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: darknesskiller (https://skillmd.com/u/darknesskiller)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/darknesskiller/codebase-design

---


# Codebase 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

1. Preserve existing boundaries unless the change is explicitly about moving them.
2. Put a rule where all callers naturally pass through it.
3. Prefer explicit request flow over hidden magic.
4. Delete speculative layers, single-use interfaces, and config for values that never vary.
5. Name domain concepts with words from `CONTEXT.md` when 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.