# Codebase Design (codebase-design)

> Provides a shared vocabulary and principles for deep modules: lots of behaviour behind a small interface, at a clean seam, tested through it.

- Category: [Architecture](https://www.myskills.tools/en/categories/architecture/)
- Source: Community · Matt Pocock
- Repository: https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design (commit 7739eae)
- SKILL.md: https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md
- Install command: `npx skills add mattpocock/skills --skill codebase-design`
- License: MIT
- Compatible with: Claude Code, Codex, Copilot, Gemini CLI
- Permissions: read-repo ✓, write-files ✗, shell ✗, network ✗
- Status: Scan passed
- A rule scan cannot catch every risk. Read this skill's SKILL.md and check its permissions before installing.

## Core rule

One adapter means a hypothetical seam, two adapters a real one: don't add a seam unless something actually varies across it.

## Execution Phases

1. **Use the shared glossary** — Use module, interface, implementation, depth, seam, adapter, leverage and locality exactly, never component, service or boundary.
2. **Judge depth** — Apply the deletion test to spot pass-throughs, and ask whether methods can be fewer, parameters simpler and more complexity hidden.
3. **Classify dependencies** — Sort dependencies into in-process, local-substitutable, remote but owned (ports and adapters) and true external (mock) to decide how to test across the seam.
4. **Design it twice** — Spawn three or more sub-agents with different constraints to produce radically different interfaces, then compare on depth, locality and seam placement and recommend one.

## Permissions (summarised from SKILL.md)

| Capability | Needed | Details |
|---|---|---|
| File writes | Not required | Supplies design vocabulary and compares options; the skill itself does not ask for files to be written. |
| Command execution | Not required | Runs no commands. |
| Network outbound | Not required | No network access. |

## SKILL.md frontmatter (YAML)

```yaml
---
name: codebase-design
description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
---
```

Home: https://www.myskills.tools/en/ · URL: https://www.myskills.tools/en/skills/codebase-design/