codebase-designcommit 7739eaeSKILL.md · Architecture
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.
npx skills add mattpocock/skills --skill codebase-designCommand selected. Copy it manually.
- Permissions
- read-repo
- write-files
- shell
- network
- Compatible with
- Claude Code, Codex, Copilot, Gemini CLI
- GitHub
- 308.7k
- Source
- Community · Matt Pocock
- Status
- Scan passed
- License
- MIT
- Category
- Architecture
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
Phase 01Use the shared glossary
Use module, interface, implementation, depth, seam, adapter, leverage and locality exactly, never component, service or boundary.
Phase 02Judge depth
Apply the deletion test to spot pass-throughs, and ask whether methods can be fewer, parameters simpler and more complexity hidden.
Phase 03Classify 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.
Phase 04Design 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)
---
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.
---