Individual skill
codebase-design
Shared vocabulary for designing deep modules — interface, seam, depth. Use when designing or improving a module's interface, placing a seam, or deciding what an API hides. Don't use for codebase-wide audits (/architecture-audit), behavior-preserving cleanup (/refactor), or UI components (/frontend-ui-engineering).
skills/codebase-design/SKILL.md
Source commit ced546848ec8eea8541e77b7aa041207b607462e
What was checked
- Matches the observed repository HEAD
- Yes
- Scanner rules are current
- No
- Repository scan complete
- No
- Skill scan complete
- Yes
- Observed behavior
- Not checked yet
- Last checked
- Nov 7, 2026
These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.
Install this skill
Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.
An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.
Repository context
- Repository stars (not skill ratings)
- 20
- Repository last updated
- Oct 26, 2026
- License
- MIT
Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.
- agent-skills Repository topic
- skills Repository topic
- cursor Repository topic
- antigravity Repository topic
- claude-code Repository topic
- agents Repository topic
- codex Repository topic
- engineering Derived category
- design Derived category
- security Derived category
- design-interface Derived category
Files and excerpt
File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.
Browse files
SKILL.mdcore · 6,199 bytesreferences/DEEPENING.mddoc · 2,562 bytesreferences/DESIGN-IT-TWICE.mddoc · 2,748 bytes
Read excerpt
# 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 and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
## Glossary
Use these terms exactly — don't 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, but also 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.
