Improve codebase architecture

Finds shallow modules worth deepening, starting from the code that changes most, shows the candidates in an HTML report with before/after diagrams and grills the chosen one with you. Use when a codebase has grown hard to test or navigate.

CodingPack: Matt Pocock's skills71 linesimprove-codebase-architecture
Author
Source
mattpocock/skills/skills/engineering/improve-codebase-architecture @ abeeaf9
License
MIT · Copyright (c) 2026 Matt Pocock

About this skill

What it does

The skill looks for deepening opportunities: refactors that turn shallow modules into deep ones, for testability and easier navigation by agents. It first decides where to look — the area you name, or else the hot spots in git log — and reads GLOSSARY.md and the ADRs there. A fresh-context subagent then walks the code and notes friction: one concept spread over many small modules, interfaces nearly as complex as their implementation, pure functions pulled out for tests while the bugs live in how they are called, leaks across seams, code hard to test. Suspects get the deletion test.

The candidates go into a self-contained HTML report in the OS temp directory, so nothing lands in the repo, and the agent opens it for you. Each card shows files, problem, solution, gains in locality and leverage, a before/after diagram and a badge: Strong, Worth exploring or Speculative. A candidate that contradicts an ADR appears only if the decision is worth reopening. After a top recommendation the agent asks which one to explore, proposing no interfaces yet.

For the chosen one it walks the decisions with you through the grilling skill, keeps GLOSSARY.md current through domain-modeling, offers an ADR when you reject a candidate for a reason future reviews need, and uses design-it-twice from codebase-design for alternative interfaces.

HTML-REPORT.md specifies the report: the scaffold, the card layout, five diagram patterns and the tone. agents/openai.yaml also turns off implicit invocation in Codex.

When to use it, and when not

Use it when a codebase has become hard to test or navigate and you want to choose what to restructure first.

It changes no code and ends with a decision. If you already know the refactor, just do it.

How to run it

The install command below puts the whole folder in place. The frontmatter sets disable-model-invocation: true, so the agent never starts it on its own; you call it:

  • Claude Code: only the /improve-codebase-architecture command — naming the skill in a message will not start it.
  • Codex: $improve-codebase-architecture.
  • Cursor: type / in the Agent chat and pick improve-codebase-architecture.

Example: /improve-codebase-architecture Focus on the checkout flow; most of this quarter's bugs came from there.

Install codebase-design, grilling and domain-modeling with it, since it calls all three. Viewing the report needs internet: Tailwind and Mermaid load from CDNs.

How it differs from similar skills

Safe refactoring from our catalog carries out a chosen refactor in small steps under tests; this skill picks the refactor and stops. Code simplification makes working code easier to read without changing behaviour, by default only in recently changed code; this skill looks at how the code is cut into modules. Codebase explainer maps an unfamiliar repo and proposes nothing.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/improve-codebase-architecture/SKILL.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md -o ~/.claude/skills/improve-codebase-architecture/HTML-REPORT.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/HTML-REPORT.md -o ~/.claude/skills/improve-codebase-architecture/LICENSE https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/LICENSE -o ~/.claude/skills/improve-codebase-architecture/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/agents/openai.yaml
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/improve-codebase-architecture/SKILL.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md -o ~/.agents/skills/improve-codebase-architecture/HTML-REPORT.md https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/HTML-REPORT.md -o ~/.agents/skills/improve-codebase-architecture/LICENSE https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/LICENSE -o ~/.agents/skills/improve-codebase-architecture/agents/openai.yaml https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/agents/openai.yaml
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','HTML-REPORT.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.claude\skills\improve-codebase-architecture" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','HTML-REPORT.md','LICENSE','agents/openai.yaml') { $p = Join-Path "$HOME\.agents\skills\improve-codebase-architecture" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/matt-pocock/improve-codebase-architecture/SKILL.md

SKILL.md

Raw

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

This command is informed by the project's domain model and built on a shared design vocabulary:

  • Call the Skill tool with "codebase-design" for the architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
  • The domain language in GLOSSARY.md gives names to good seams; ADRs in docs/adr/ record decisions this command should not re-litigate.

Process

1. Explore

Scope before you scan: YAGNI. Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide where to look before you look:

  • If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
  • Otherwise, walk back a good stretch of the commit history (git log --oneline) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.

Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:

  • Where does understanding one concept require bouncing between many small modules?
  • Where are modules shallow, with an interface nearly as complex as the implementation?
  • Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
  • Where do tightly-coupled modules leak across their seams?
  • Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/architecture-review-<timestamp>.html so each run gets a fresh file. Open it for the user (xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows) and tell them the absolute path.

The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.

For each candidate, render a card with:

  • Files: which files/modules are involved
  • Problem: why the current architecture is causing friction
  • Solution: plain English description of what would change
  • Benefits: explained in terms of locality and leverage, and how tests would improve
  • Before / After diagram: side-by-side, custom-drawn, illustrating the shallowness and the deepening
  • Recommendation strength: one of Strong, Worth exploring, Speculative, rendered as a badge

End the report with a Top recommendation section: which candidate you'd tackle first and why.

Use GLOSSARY.md vocabulary for the domain, and the /codebase-design vocabulary for the architecture. If GLOSSARY.md defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.

See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.

Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"

3. Grilling loop

Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:

  • Naming a deepened module after a concept not in GLOSSARY.md? Add the term to GLOSSARY.md. Create the file lazily if it doesn't exist.
  • Sharpening a fuzzy term during the conversation? Update GLOSSARY.md right there.
  • User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
  • Want to explore alternative interfaces for the deepened module? Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Matt Pocock's skills

Code review against standards and spec

Reviews the diff since a commit, branch or tag on two axes in parallel subagents: the repo's written standards plus a baseline of Fowler code smells, and the originating spec or issue. Use when a branch or PR needs checking against its spec.

Deep module design

Fixes a shared vocabulary for deep modules (interface, seam, adapter, depth, leverage), with the deletion test, dependency categories and a design-it-twice pattern on parallel subagents. Use when designing a module's interface or deciding where a seam goes.

Diagnosing hard bugs

Diagnoses hard bugs and slowdowns by first building a fast, deterministic command that reproduces the exact symptom, then minimising it, ranking falsifiable hypotheses and adding a regression test at a real seam. Use when something fails, throws or got slow.

Domain modeling

Sharpens a project's domain language during design: challenges fuzzy or conflicting terms, writes resolved ones to GLOSSARY.md at once and offers a short ADR only for hard-to-reverse trade-offs. Use when discussing terminology or recording an ADR.

Implement a spec

Implements a spec and its tickets on one integration branch: a fresh implementer subagent per ticket in its own worktree, run in parallel along the blocking graph, then a code review and one fix pass. Use when the tickets from to-tickets are ready.

Throwaway prototype

Builds throwaway code to answer one design question: a single-file clickable HTML demo for a state model, or several structurally different UI variants on one route switched by a URL param. Use when checking whether logic holds or how a page should look.

Coding session retrospective

Reviews a finished coding session from its logs and proposes changes to the agent's environment: navigation pointers, lint rules, pre-commit and CI checks, reviewer standards, tool use. Use when an agent session went slowly or made avoidable mistakes.

TDD with integration tests

Drives test-first work through public interfaces: agrees the seams to test with the user, runs one red-green cycle per test, mocks only at system boundaries and leaves refactoring to review. Use when building a feature or fixing a bug test-first.

Conversation to spec

Turns the current conversation and codebase into a spec with user stories, implementation and testing decisions, and publishes it to the issue tracker as ready-for-agent, without interviewing the user. Use when a discussed feature needs writing up.

Spec to tickets

Splits a spec, plan or conversation into tracer-bullet tickets, vertical slices that each fit one agent session, with blocking edges, and publishes them as local files or tracker issues. Use when work is too big for one session and needs a task graph.

Issue and PR triage

Triages issues and external PRs on the tracker: gives each a category and a state, checks for existing code and past rejections, reproduces bugs and writes agent briefs for ready work. Use when a maintainer works through incoming issues and PRs.

Wayfinder for huge work

Charts work too big for one agent session as a map issue with child decision tickets on the tracker, then resolves one ticket per session until the route to the goal is clear. Use when a large effort has open questions that block a spec or plan.

Bash wizard for manual steps

Generates an interactive bash script that walks a person through manual steps such as dashboard setup, API keys and CI secrets, opening each URL and saving values to .env and GitHub secrets. Use when setup or a migration needs steps only a human can take.

Git guardrails for Claude Code

Installs a Claude Code PreToolUse hook that stops the usual forms of git push, reset --hard, clean -f, branch -D and checkout or restore of the whole tree, for one project or all, then tests it. Use when you want a safety net against an agent pushing or discarding work on its own.

Migrate tests to shoehorn

Replaces as and as unknown as casts in TypeScript tests with fromPartial and fromAny from @total-typescript/shoehorn, adds the imports and runs the type check. Use when tests fake whole objects or cast partial test data to satisfy the compiler.

Pre-commit hooks setup

Sets up Husky and lint-staged in a Node repo so each commit runs Prettier on staged files, then the typecheck and test scripts, matched to the lockfile, and makes the first commit through the hook. Use when a repo has no commit-time checks.

Grilling a plan

Questions the user about a plan or decision in rounds of numbered questions with recommended answers, looks facts up itself through subagents and stops only when no decision is left assumed. Use when a plan needs stress-testing before work starts.

Teach me a topic

Runs a multi-session course in the current folder: a mission, trusted sources, short HTML lessons with quizzes, reference sheets and learning records that set the next lesson. Use when the user wants to learn a topic over time, not get one answer.

Decision questionnaire

Writes a Markdown questionnaire for someone who holds knowledge the user lacks, after asking only who it goes to and what answers are needed, with the most important questions first. Use when a decision depends on facts from another person.

Writing for agents

Gives the rules for writing text agents read: skill descriptions as context pointers, what to keep inline and what to move to a separate file, completion criteria, leading words and pruning. Use when creating or editing a skill, AGENTS.md or CLAUDE.md.