---
title: Codebase Design Skill for Claude Code
canonical: https://skillselion.com/guides/codebase-design-skill-claude-code
content_type: text/markdown
description: "codebase-design is Matt Pocock's Claude Code skill for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, tested through."
---

# Codebase Design Skill for Claude Code: Deep Modules and Seams

Title: Codebase Design Skill for Claude Code

> codebase-design is Matt Pocock's Claude Code skill for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, tested through.

Canonical: https://skillselion.com/guides/codebase-design-skill-claude-code

codebase-design is Matt Pocock's Claude Code skill for designing deep modules: a lot of behaviour behind a small interface, at a clean seam, tested through that interface. It has 982,730 installs and defines eight exact terms. Pair it with improve-codebase-architecture (1,294,711 installs) to find refactors in a real repo.

## Key facts

- Last updated: November 12, 2026

## Article

"Clean up this module" is a vague request, and an agent needs a target shape before it restructures code. Matt Pocock's [codebase-design skill](/skills/mattpocock/skills/codebase-design) (982,730 installs, 329,813 GitHub stars) gives Claude Code a stricter goal: deep modules, with a lot of behaviour behind a small interface.

## Key takeaways

- codebase-design has 982,730 installs (skills.sh registry) and defines eight terms the agent must use exactly: module, interface, implementation, depth, seam, adapter, leverage and locality.
- It is a vocabulary skill with eight terms and a few principles. [improve-codebase-architecture](/skills/mattpocock/skills/improve-codebase-architecture) (1,294,711 installs) is the command that scans a repo and loads codebase-design for its terms.
- Its seam rule is short: one adapter means a hypothetical seam, two adapters means a real one.
- The deletion test decides whether a module earns its place: delete it, and if complexity reappears across many callers, keep it.
- The [tdd skill](/skills/mattpocock/skills/tdd) (1,268,196 installs) uses the same idea of seams to decide where tests go.

## What does the codebase-design skill do?

It makes Claude Code design and discuss code in one fixed vocabulary. A **module** is anything with an interface and an implementation, from a function to a slice that crosses tiers. The **interface** is everything a caller must know: types, but also invariants, ordering rules, error modes, configuration and performance. **Depth** is leverage at that interface, meaning how much behaviour a caller or test can exercise per unit of interface it has to learn. The skill bans the words "component", "service", "API" and "boundary" in this context, because consistent language is the point. The skill has 982,730 installs and the mattpocock/skills repo has 329,813 stars (skills.sh registry, [mattpocock/skills on GitHub](https://github.com/mattpocock/skills)).

## How do you install codebase-design in Claude Code?

Run one command in your project:

`npx skills add https://github.com/mattpocock/skills --skill codebase-design`

![Matt Pocock avatar on GitHub](https://github.com/mattpocock.png?size=200)

The skill loads when you ask the agent to design or improve a module's interface, find a deepening opportunity, decide where a seam goes, or make code more testable. Other skills also call it: improve-codebase-architecture tells the agent to load codebase-design before it suggests anything, so its suggestions use the same eight terms. A Chinese translation by vinvcn ([codebase-design zh-cn](/skills/vinvcn/mattpocock-skills-zh-cn/codebase-design)) has 4,453 installs.

## When should you add a seam to your code?

Only when something actually varies across it. A **seam**, a term the skill credits to Michael Feathers, is a place where you can change behaviour without editing that place. The skill's rule is that one adapter is only a hypothetical seam, and a second adapter, usually a test fake next to the production one, makes it real. A port with one adapter is just indirection. The companion DEEPENING.md file sorts dependencies into four groups: in-process, local-substitutable (PGLite for Postgres), remote but owned (ports and adapters) and true external services such as Stripe, which get a mock adapter in tests.

## How does codebase-design make code easier to test?

It treats the interface as the test surface: callers and tests cross the same seam. If a test has to reach past the interface, the module is probably the wrong shape. The skill gives three rules: accept dependencies instead of creating them, return results instead of producing side effects, and keep the surface small, since fewer methods need fewer tests. After a cluster of shallow modules is merged, DEEPENING.md says to delete the old unit tests and write new ones at the deeper interface. The [TDD skill guide](/guides/tdd-skill-claude-code-guide) shows the red-green loop that builds on these seams.

## How is codebase-design different from improve-codebase-architecture?

codebase-design is the dictionary and improve-codebase-architecture is the job. The architecture command (1,294,711 installs) walks recent git history, finds friction, writes a visual HTML report of deepening opportunities and then grills you through the one you pick. codebase-design (982,730 installs) holds the terms and principles that report uses. Its DESIGN-IT-TWICE.md file adds one more step: spin up 3 or more sub-agents in parallel, each told to design a radically different interface (minimal, flexible, common-caller, ports and adapters), then compare them on depth, locality and seam placement. The [improve-codebase-architecture guide](/guides/improve-codebase-architecture-skill-claude-code) covers the scan in detail.

## A complete starter stack

- codebase-design (982,730 installs): the shared vocabulary and seam rules.
- improve-codebase-architecture (1,294,711 installs): finds deepening opportunities in a real repo.
- tdd (1,268,196 installs): writes tests at the seams you agreed on.

## Common pitfalls

- Expecting a step-by-step process. codebase-design is a reference of 8 terms and a handful of principles; pair it with improve-codebase-architecture when you want the agent to act.
- Adding a port for every dependency. With one adapter it is a hypothetical seam, and the skill says not to introduce it.
- Keeping old unit tests after deepening. DEEPENING.md calls them waste once tests exist at the new interface, and they lock the old shape in place.

Install codebase-design first, then see the [best testing and review skills](/best/skills-for-testing-review) for the rest of the quality stack, or browse the full [testing and review category](/category/testing-review).

## Related

- [/best/skills-for-testing-review](https://skillselion.com/best/skills-for-testing-review)
- [/category/testing-review](https://skillselion.com/category/testing-review)
- [/guides/improve-codebase-architecture-skill-claude-code](https://skillselion.com/guides/improve-codebase-architecture-skill-claude-code)
- [/guides/tdd-skill-claude-code-guide](https://skillselion.com/guides/tdd-skill-claude-code-guide)
- [/guides/matt-pocock-skills-map](https://skillselion.com/guides/matt-pocock-skills-map)

## FAQ

### What is the codebase-design skill?

codebase-design is a vocabulary skill from Matt Pocock (982,730 installs) that defines eight exact terms for module design, from module and interface to leverage and locality. See [codebase-design](/skills/mattpocock/skills/codebase-design).

### How do I install the codebase-design skill?

Run `npx skills add https://github.com/mattpocock/skills --skill codebase-design`. The repo has 329,813 GitHub stars. Browse related skills on the [best testing and review skills](/best/skills-for-testing-review) page.

### What is a deep module?

A deep module puts a lot of behaviour behind a small interface, so callers get leverage and maintainers get locality. The codebase-design skill (982,730 installs) defines depth as leverage at the interface. See [codebase-design](/skills/mattpocock/skills/codebase-design).

### When should I add a seam?

Only when something varies across it. codebase-design (982,730 installs) says one adapter means a hypothetical seam and two adapters mean a real one. See the [TDD skill guide](/guides/tdd-skill-claude-code-guide) for where tests sit on a seam.

### What is the difference between codebase-design and improve-codebase-architecture?

codebase-design (982,730 installs) holds the vocabulary. improve-codebase-architecture (1,294,711 installs) scans the repo, writes an HTML report and loads codebase-design for its terms. See [improve-codebase-architecture](/skills/mattpocock/skills/improve-codebase-architecture).

## Machine access

- [Sitemap](https://skillselion.com/sitemap.xml)
- [llms.txt](https://skillselion.com/llms.txt)
- [llms-full.txt](https://skillselion.com/llms-full.txt)
- [Developer resources](https://skillselion.com/developers)
- [OpenAPI spec](https://skillselion.com/openapi.json)
- [MCP handshake](https://skillselion.com/.well-known/mcp)
- [API catalog](https://skillselion.com/.well-known/api-catalog)
- [AI catalog](https://skillselion.com/.well-known/ai-catalog.json)
- [Pricing](https://skillselion.com/pricing.md)
- [Auth](https://skillselion.com/auth.md)
- [AGENTS.md](https://skillselion.com/AGENTS.md)
- [Contact](https://skillselion.com/contact)
- [Home](https://skillselion.com/)
