| name | improve-codebase-architecture |
| description | Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. |
| disable-model-invocation | true |
| category | development |
| risk | safe |
| source | community |
| source_repo | mattpocock/skills |
| source_type | community |
| date_added | 2026-06-19 |
| author | Matt Pocock |
| license | MIT |
| license_source | https://github.com/mattpocock/skills/blob/main/LICENSE |
| tags | ["engineering","workflow","coding-agents"] |
| tools | ["claude-code","codex-cli","cursor"] |
Improve Codebase Architecture
When to Use
Use when this workflow matches the user request: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
Source: mattpocock/skills (MIT).
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:
- Run the
/codebase-design skill 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 — don't drift into "component," "service," "API," or "boundary."
- The domain language in
CONTEXT.md gives names to good seams; ADRs in docs/adr/ record decisions this command should not re-litigate.
Process
1. Explore
Read the project's domain glossary (CONTEXT.md) and any ADRs in the area you're touching first.
Then use the Agent tool with subagent_type=Explore 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 — 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 so each run gets a fresh file. Open it for the user — on Linux, on macOS, on Windows — and tell them the absolute path.
