Matt Pocock's /improve-codebase-architecture command: finds shallow modules worth deepening, renders them as a visual HTML report with before/after diagrams, then grills you through the one you pick.
Codebase Design Skill
Matt Pocock's skill that gives coding agents a shared vocabulary for designing deep modules: interfaces, seams, adapters, depth, leverage and locality, plus rules for testable design.
Install
Other ways to install
About
- Defines module, interface, seam, adapter, depth, leverage and locality precisely
- Depth measured as leverage at the interface, not a line-count ratio
- Deletion test for spotting pass-through modules
- Testability rules: inject dependencies, return results, keep the surface small
- Companion guides for deepening a module cluster and designing an interface twice
- Shared vocabulary used by other skills in the collection
Codebase Design is one of the engineering skills in Matt Pocock's mattpocock/skills collection. It is a vocabulary skill: rather than running a workflow, it fixes the words an agent uses when it designs or restructures code, so that conversations about architecture stay precise. The agent loads it when you want to design or improve a module's interface, look for places to deepen a module, decide where a seam should go, or make code easier to test and to navigate for AI agents. Other skills in the collection, such as Improve Codebase Architecture, rely on it.
The core idea comes from John Ousterhout's deep modules: a lot of behaviour behind a small interface. The skill defines module, interface (everything a caller must know, including invariants, error modes and performance, not just the type signature), implementation, depth, seam (after Michael Feathers), adapter, leverage and locality, and tells the agent to avoid looser words such as component, service or boundary. It measures depth as leverage at the interface rather than as a ratio of implementation lines to interface lines, which it says rewards padding.
Practical principles follow: the deletion test (if deleting a module makes complexity reappear across callers, it was earning its keep), the interface as the test surface, and "one adapter is a hypothetical seam, two adapters is a real one". For testability it asks for injected dependencies, returned results instead of side effects, and small surfaces. Companion files cover deepening a cluster of modules and designing an interface several radically different ways with parallel sub-agents. MIT licensed.
SKILL.md
The instructions your agent loads, as published by Matt Pocock.
Related Skills
See all Codebase Design alternativesSkill: Code Simplification
by Addy Osmani
Reduces accumulated complexity without changing behaviour, using Chesterton's Fence to avoid deleting the thing that was load-bearing.
Matt Pocock's test-driven development skill: one red-to-green slice at a time, tests only at seams agreed with you first, and a named list of test anti-patterns to avoid.
Matt Pocock's discipline for hard bugs and performance regressions: build a tight, red-capable feedback loop first, then reproduce, minimise, hypothesise, instrument, fix with a regression test and clean up.