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.
improve-codebase-architecture- Author
- Matt Pocock
- 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-architecturecommand — naming the skill in a message will not start it. - Codex:
$improve-codebase-architecture. - Cursor: type
/in the Agent chat and pickimprove-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.
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
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
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 }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
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.mdgives names to good seams; ADRs indocs/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 toGLOSSARY.md. Create the file lazily if it doesn't exist. - Sharpening a fuzzy term during the conversation? Update
GLOSSARY.mdright 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.
AnyModel