improve-architecture
Assess a codebase's architecture, stop when it is healthy, otherwise find deepening opportunities, design the chosen one, and hand a plan to /implement.
svyatov · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add svyatov/supermatt --skill improve-architectureAbout this skill
name: improve-architecture description: "Assess a codebase's architecture, stop when it is healthy, otherwise find deepening opportunities, design the chosen one, and hand a plan to /implement." argument-hint: "[module, subsystem, or pain point]" disable-model-invocation: true compatibility: Uses git to find hot spots. license: MIT
Improve Architecture
Explore a codebase, surface architectural friction, and propose deepening opportunities: refactors that turn shallow modules into deep ones, for testability and AI-navigability. Starts with an assessment: if the architecture is already healthy, say so and stop. Ends with a plan that /implement builds; this skill changes no code.
This skill is built on a shared vocabulary and informed by the project's domain model:
- Load and follow the
codebase-designskill through the host's skill mechanism first. Use its terms exactly (module, interface, depth, seam, adapter, leverage, locality, information leakage) and don't drift into "component," "service," "API," or "boundary." ItsRED-FLAGS.mdnames structural defects, itsDEEPENING.mdholds the dependency categories and seam discipline, and itsDESIGN-IT-TWICE.mdholds the parallel interface design. - The domain language in
GLOSSARY.mdgives names to good seams; ADRs record decisions this skill should not re-litigate.docs/agents/domain.mdgives where both live (by defaultGLOSSARY.mdanddocs/adr/at the root).
Architecture vs refactoring: this skill handles structural changes: module boundaries, interfaces, testability. If the problem is code-level (complexity, duplication, naming, dead code within a well-bounded module), that's refactoring: tell the user to run /refactor in Claude linked installs or Cursor, /supermatt:refactor from the Claude plugin, $refactor in Codex, or /skill:refactor in OMP. The same applies after an architectural change lands: cleaning up the new module's internals is a separate refactoring pass.
Guardrails
- Deep is not big. A deep module hides complexity behind a small interface; it does not own every concern it touches. If describing the proposed module requires "and" more than once, it's a god object, not a deep module. Split it. Deep modules can delegate internally to focused collaborators while presenting a simple interface.
- Separate, don't combine. Deepening means consolidating a single concept scattered across many files. It does not mean merging unrelated concepts that happen to be called together. Before proposing a merge, ask: "Are these the same concern, or just co-located?"
- Architecture has a ceiling. Not every codebase benefits from restructuring. Small projects (<20 files) with low coupling rarely need architectural intervention. The default verdict is Healthy: do not invent structural work.
- Every new element must pay for itself. An interface, an argument, a class, a port: each one adds complexity, because someone has to learn it. To be a net gain it must remove more complexity than it introduces. This applies to anything this skill proposes creating.
Process
Step 1: Explore the codebase
1a. Scope before you scan
Deepening a module pays off by making future changes to it easier, so weight the parts that actually keep changing. 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 rest of this step.
- Otherwise, find the hot spots: files that change often and are complex. Count the changes per file over the last year with
git log --since="12 months ago" --name-only --pretty=format:. Leave out bot commits and bulk reformat or move commits, because they inflate every file they touch. Rank the most-changed files by complexity, and let the top paths pull your attention first. - If the changes are scattered with no clear hot spot, widen the net to the whole codebase.
Everything below operates on the scoped area, not necessarily the whole repository. Read the glossary and the ADRs that cover it.
1b. Map the structure
Before exploring for friction, have a fresh read-only exploration subagent produce a structural inventory of the scoped area and return only the map. If no independent context is available, produce the map yourself and report that independence gap:
- List all modules/packages in scope with approximate size (file count, rough line count)
- Trace the dependency graph: which modules import which
- Flag circular dependencies
- For each module: number of exported symbols, number of callers, found with a symbol-aware search (LSP find references, CodeGraph) where available; mark grep-based counts
grep-only
This map is your baseline. It prevents incomplete analysis across multiple sessions. Record the scope you chose in 1a alongside it.
1c. Explore for friction
Read the scoped hot spots yourself, guided by the map from 1b: the verdict, the candidates, and the interface design briefs (paths + key line ranges) all rest on code you have seen. Read one file per call, so no result goes over the output limit and has to be read a second time from a saved file. Use fresh read-only exploration subagents only for sweeps outside the hot spots. When the host has no independent context, perform those sweeps sequentially and report the gap. Name each friction with a codebase-design red flag where one fits, since naming the flag is half the diagnosis. Note where you experience friction:
- Where does understanding one concept require bouncing between many small files?
- Where are modules shallow, with an interface nearly as complex as the implementation?
- Where is the same design decision encoded in two or more modules (information leakage)? This is the most expensive structural defect to leave in place. Watch especially for back-door leakage: knowledge shared between modules without appearing in either interface.
- Where have pure