# improve-codebase-architecture

> A Matt Pocock Claude Code skill that surfaces architectural friction and proposes deepening opportunities — refactors that turn shallow modules into deep ones — using a precise Ousterhout-style vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) defined in a bundled LANGUAGE.md and informed by the project's CONTEXT.md and docs/adr/.

**Use case**: Find deepening opportunities in a codebase

**Canonical URL**: https://agentcookbooks.com/skills/improve-codebase-architecture/

**Topics**: claude-code, skills, architecture, refactoring

**Trigger phrases**: "improve the architecture", "find refactoring opportunities", "make this more AI-navigable", "deepening opportunities"

**Source**: [Matt Pocock](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture)

**License**: MIT

---

## What it does

`improve-codebase-architecture` reads a codebase against its own shared context (`CONTEXT.md`, `docs/adr/`) and proposes **deepening opportunities** — refactors that turn shallow modules into deep ones, where "deep" means a lot of behaviour behind a small interface.

The skill enforces a precise vocabulary throughout, defined in a bundled `LANGUAGE.md`. The key terms (used exactly — no drift into "component," "service," "API," or "boundary"):

- **Module** — anything with an interface and an implementation (function, class, package, slice).
- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
- **Implementation** — the code inside.
- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation.
- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
- **Adapter** — a concrete thing satisfying an interface at a seam.
- **Leverage** — what callers get from depth.
- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.

The **deletion test** is the operative diagnostic: imagine deleting the module. If complexity vanishes, it was a pass-through — consolidate or inline. If complexity reappears across N callers, the module was earning its keep — the depth is real.

## When to use it

Reach for it when:

- A codebase has accumulated shallow modules and the agent is burning compute reading glue instead of behaviour
- You're about to onboard another engineer or agent and want the interfaces to be load-bearing rather than ceremonial
- A feature plan keeps tripping on the same module that *looks* like a seam but isn't actually pulling weight
- You have a `CONTEXT.md` and ADRs maintained — the skill is sharper with that vocabulary anchor

When *not* to reach for it:

- Greenfield code where the architecture isn't settled enough for deepening to mean anything
- Codebases without `CONTEXT.md` — the skill works but the suggestions degrade into generic refactor advice without the project's domain anchor
- When the actual problem is dependency direction, not module depth — reach for `hexagonal-architecture` instead

## Install

The skill is distributed via Pocock's [skills repo](https://github.com/mattpocock/skills). Install via his recommended path (`npx skills add` or manual copy of the `SKILL.md` + `LANGUAGE.md` sub-doc into `.claude/skills/improve-codebase-architecture/`) — see the repo README for canonical install instructions.

The skill expects `CONTEXT.md` at the project root and ADRs in `docs/adr/` to be set up — use `setup-matt-pocock-skills` to scaffold them if they don't exist yet.

## What a session looks like

A typical session has three phases:

1. **Read the context.** The skill reads `CONTEXT.md` and the ADR record before touching the code, so every suggestion is in domain vocabulary.
2. **Apply the deletion test.** For each candidate module, imagine deleting it. The skill flags pass-throughs (consolidate) vs leverage-earners (keep) vs the in-between cases that need a seam pulled out.
3. **Propose deepenings.** Each suggestion is in the fixed vocabulary — never drifting into "let's extract a service" or "let's add a boundary." The output is a small list of refactors with the depth-vs-shallow argument made explicit.

The discipline that makes it work: vocabulary consistency. The same word means the same thing in every suggestion, every ADR, every code review.

Different angle from [`tech-debt-tracker`](/skills/tech-debt-tracker/) (which scans for code-quality signals) and [`hexagonal-architecture`](/skills/hexagonal-architecture/) (which prescribes ports-and-adapters as a specific dependency-direction pattern). `improve-codebase-architecture` is about *depth* — how much behaviour each interface earns — which is upstream of both.

## Receipts

TODO — to be filled in from a real session. When the skill is triggered in production use, capture: how many deepening opportunities surfaced, whether the deletion test flagged any pass-through module that survived a recent review, whether the vocabulary stayed consistent across the suggestions, and whether the proposed refactors actually compressed the interface vs just renaming it.

## Source and attribution

Originally written by [Matt Pocock](https://github.com/mattpocock). The canonical `SKILL.md` plus the `LANGUAGE.md` sub-doc live in the [`engineering/improve-codebase-architecture` folder](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture) of his public skills repository.

The depth/seam/adapter/leverage vocabulary draws on John Ousterhout's *A Philosophy of Software Design*. The skill is Pocock's distillation into a Claude-Code-loadable form, not the source material itself.

License: MIT. You can install, adapt, and redistribute the skill, with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.