improve-codebase-architecture

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• improve the architecture
• find refactoring opportunities
• make this more AI-navigable
• deepening opportunities

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. 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 (which scans for code-quality signals) and 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. The canonical SKILL.md plus the LANGUAGE.md sub-doc live in the engineering/improve-codebase-architecture folder 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.