codebase-design skill
✓ VerifiedProvides a shared vocabulary and principles for designing deep modules with small interfaces and high leverage.
- GitHub stars
- 7
- Files
- 3
- Last commit
- Nov 6, 2026
- License
- MIT
- Allowed tools
- —
What does the codebase-design skill do?
codebase-design provides a shared vocabulary and principles for designing deep modules with small interfaces and high leverage.
Summary generated from the skill's SKILL.md.
How to install the codebase-design skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the codebase-design skill in Plugin
/plugin marketplace add HigorAlves/orc /plugin install orc@orc
Install the codebase-design skill in Claude Code
~/.claude/skills/codebase-design/SKILL.md
$ npx degit HigorAlves/orc/orc/skills/codebase-design ~/.claude/skills/codebase-designInstall the codebase-design skill in Claude Code (project)
.claude/skills/codebase-design/SKILL.md
$ npx degit HigorAlves/orc/orc/skills/codebase-design .claude/skills/codebase-designInstall the codebase-design skill in Codex
~/.agents/skills/codebase-design/SKILL.md
$ npx degit HigorAlves/orc/orc/skills/codebase-design ~/.agents/skills/codebase-designInstall the codebase-design skill in Gemini CLI
~/.gemini/skills/codebase-design/SKILL.md
$ npx degit HigorAlves/orc/orc/skills/codebase-design ~/.gemini/skills/codebase-designInstall the codebase-design skill in Claude.ai
npx degit HigorAlves/orc/orc/skills/codebase-design codebase-design && zip -r codebase-design.zip codebase-design # claude.ai → Customize → Skills → + → Create skill → Upload a skill → codebase-design.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablehigoralves/orc/orc/skills/codebase-design is public and reachablegithub.com/higoralves/orc/tree/HEAD/orc/skills/codebase-desi ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-06github.com/higoralves/orc/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/higoralves/orc/blob/HEAD/orc/skills/codebase-desi ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/higoralves/orc/blob/HEAD/orc/skills/codebase-desi ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/higoralves/orc/blob/HEAD/orc/skills/codebase-desi ↗Finding
SKILL.md
View on GitHubCodebase 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.
Depth — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is deep when a large amount of behaviour sits behind a small interface, shallow when the interface is nearly as complex as the implementation.
Seam (Michael Feathers) — a place where you can alter behaviour without editing in that place; the location at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. Avoid: boundary (overloaded with DDD's bounded context).
Adapter — a concrete thing that satisfies an interface at a seam. Describes role (what slot it fills), not substance (what's inside).
Leverage — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
Locality — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
Deep vs shallow
Deep module = small interface + lots of implementation:
┌─────────────────────┐
│ Small Interface │ ← Few methods, simple params
├─────────────────────┤
│ │
│ Deep Implementation│ ← Complex logic hidden
│ │
└─────────────────────┘
Shallow module = large interface + little implementation (avoid):
┌─────────────────────────────────┐
│ Large Interface │ ← Many methods, complex params
├─────────────────────────────────┤
│ Thin Implementation │ ← Just passes through
└─────────────────────────────────┘
When designing an interface, ask:
- Can I reduce the number of methods?
- Can I simplify the parameters?
- Can I hide more complexity inside?
Principles
- Depth is a property of the interface, not the implementation. A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface.
- The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
- One adapter means a hypothetical seam. Two adapters means a real one. Don't introduce a seam unless something actually varies across it.
Designing for testability
Good interfaces make testing natural:
-
Accept dependencies, don't create them.
// Testable function processOrder(order, paymentGateway) {} // Hard to test function processOrder(order) { const gateway = new StripeGateway(); } -
Return results, don't produce side effects.
// Testable function calculateDiscount(cart): Discount {} // Hard to test function applyDiscount(cart): void { cart.total -= discount; } -
Small surface area. Fewer methods = fewer tests needed. Fewer params = simpler test setup.
Relationships
- A Module has exactly one Interface (the surface it presents to callers and tests).
- Depth is a property of a Module, measured against its Interface.
- A Seam is where a Module's Interface lives.
- An Adapter sits at a Seam and satisfies the Interface.
- Depth produces Leverage for callers and Locality for maintainers.
Rejected framings
- Depth as ratio of implementation-lines to interface-lines (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
- "Interface" as the TypeScript
interfacekeyword or a class's public methods: too narrow — interface here includes every fact a caller must know. - "Boundary": overloaded with DDD's bounded context. Say seam or interface.
Going deeper
- Deepening a cluster given its dependencies — see references/DEEPENING.md: dependency categories, seam discipline, and replace-don't-layer testing.
- Exploring alternative interfaces — see references/DESIGN-IT-TWICE.md: spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.
Files in this skill
3codebase-design skill questions
How do I install the codebase-design skill in Claude Code?
Run npx degit HigorAlves/orc/orc/skills/codebase-design ~/.claude/skills/codebase-design. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the codebase-design skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is a deep module?
A deep module is one that provides a lot of behavior behind a small interface, offering leverage to callers and locality to maintainers.
What is the difference between an interface and an API?
An interface includes everything a caller must know to use a module correctly, such as type signatures, invariants, error modes, and performance characteristics, whereas an API is often used too narrowly to refer only to the type-level surface.