WEB DEVELOPMENT / Matt Pocock
Matt Pocock Codebase Design
Evaluates module boundaries through caller complexity, dependency seams and alternative interface designs.
“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.”
01 / THE REASONING
Why this made the selection.
- Defines a deep module by what callers can accomplish through a small interface, rather than by its line count.
- Distinguishes internal dependencies, local substitutes and external boundaries, then compares alternative interfaces before choosing a design.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- skills/engineering/codebase-design/DEEPENING.md
- skills/engineering/codebase-design/DESIGN-IT-TWICE.md
- skills/engineering/codebase-design/SKILL.md
- skills/engineering/codebase-design/agents/openai.yaml
- skills/engineering/setup-matt-pocock-skills/SKILL.md
- skills/engineering/setup-matt-pocock-skills/agents/openai.yaml
- skills/engineering/setup-matt-pocock-skills/domain.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
- skills/engineering/setup-matt-pocock-skills/triage-labels.md
- README.md (installation and setup sections; the README has no licence section)
- LICENSE (MIT, copyright 2026 Matt Pocock)
Our findings
- The definition, deepening guide and alternative-design guide were all inspected. They give a shared vocabulary and a concrete comparison procedure.
- The skill can guide changes to code and tests but supplies no executable check that the resulting interface is better.
- The SKILL.md rejects Ousterhout's ratio of implementation lines to interface lines as a depth measure and uses leverage per unit of interface instead. It also states that one adapter means a hypothetical seam and two adapters a real one.
- DEEPENING.md sorts dependencies into in-process, local-substitutable, remote but owned, and true external, and gives each a test strategy: merge and test directly, a local stand-in such as PGLite, an in-memory adapter behind a port, or a mock adapter.
- DESIGN-IT-TWICE.md asks for three or more parallel sub-agents, each under a different constraint (minimal interface, maximum flexibility, common caller, ports and adapters), then a comparison on depth, locality and seam placement ending in one recommendation.
- Re-pinned from c55ee46073ed923f86ce59a5eb3b6d895095d1b7 to 49dd158d1076134a641b33efb035946536778336: SKILL.md and DEEPENING.md are unchanged. DESIGN-IT-TWICE.md now names GLOSSARY.md instead of CONTEXT.md as the source of domain vocabulary for sub-agent briefs. At this revision the setup companion also creates any configured triage label the GitHub or GitLab tracker lacks (gh label create / glab label create), when the triage skill is installed.
Not established by this review
- No refactor or interface comparison was performed.
- No claim of reduced defects, token usage or maintenance time was measured.
- Not executed: it was not installed or run.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
DOCUMENTED COMMAND
npx skills add mattpocock/skills --skill codebase-design --skill setup-matt-pocock-skills Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.
Optional: install the reviewed revision
Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.
npx skills add https://github.com/mattpocock/skills/tree/49dd158d1076134a641b33efb035946536778336 --skill codebase-design --skill setup-matt-pocock-skills - Keep DEEPENING.md and DESIGN-IT-TWICE.md with the installed definition.
- Choose a bounded module or seam and review the proposed design before authorizing code or test replacement.
- The publisher recommends setup-matt-pocock-skills as a separate companion. Review its repository documentation and issue-tracker changes before running it.
- Choose your AI tools and project or global scope in the installer. The source revision shown here is the one reviewed; the installer itself is not executed or version-pinned by this review.
- For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/mattpocock-codebase-design/bundle.zip and extract it into a new directory. It holds SKILL.md and 3 supporting files unchanged at revision 49dd158d, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named codebase-design. Keep SKILL.md and the licence together.
Before you start
- Node.js/npm and git for the documented Skills installer
- A codebase and its tests
- Subagent support for the optional independent-interface exercise; project domain vocabulary when using that exercise
- The separately selected setup companion establishes the repository conventions; review its proposed AGENTS.md or CLAUDE.md and docs/agents edits before accepting them.
THE COMPLETE REVIEWED DEFINITION
Read it before you reuse it.
Original source bytes, with attribution.
Review the host-specific setup notes above.
---
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.
---
# 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.
**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:
1. **Accept dependencies, don't create them.**
```typescript
// Testable
function processOrder(order, paymentGateway) {}
// Hard to test
function processOrder(order) {
const gateway = new StripeGateway();
}
```
2. **Return results, don't produce side effects.**
```typescript
// Testable
function calculateDiscount(cart): Discount {}
// Hard to test
function applyDiscount(cart): void {
cart.total -= discount;
}
```
3. **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 `interface` keyword 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 [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
- **Exploring alternative interfaces**, see [DESIGN-IT-TWICE.md](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.
The download contains SKILL.md. Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.
By Matt Pocock. Exact upstream source ↗ · Licence · Attribution
SHA-256 2c20617f87ec8af6a434859f381b2f061a69b530444e74eb39e78bb016a6d1e2
Read the applicable licence
MIT License Copyright (c) 2026 Matt Pocock Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/codebase-design/SKILL.md
Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/codebase-design/DEEPENING.md
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/codebase-design/DESIGN-IT-TWICE.md
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/SKILL.md
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/domain.md
Supports: review, limitations, install, access
- Reviewed reference or helper: skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md ↗Checked
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
Supports: review, limitations, install, access
- Reviewed reference or helper: skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md ↗Checked
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
Supports: review, limitations, install, access
- Reviewed reference or helper: skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md ↗Checked
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/triage-labels.md
Supports: review, limitations, install, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/README.md
Supports: install, compatibility, access
https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/LICENSE
Supports: license, access.cost
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts
Supports: install
https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts
Supports: install
https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/skills/engineering/codebase-design/SKILL.md
Supports: bestFor, review
https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/README.md
Supports: limitations