Improve Codebase Architecture (Claude Code skill)
You invoke /improve-codebase-architecture when the codebase becomes hostile to both you and Claude, modules too thin, responsibilities smeared, tests breaking on every refactor. The skill hunts 'deepening opportunities' (turning shallow into deep) with one killer test: the 'deletion test', if you delete this module, does complexity vanish, or does it reappear across 5 callers? Distributed by Matt Pocock in his skills repo.
Strengths
- The 'deletion test' (does deleting the module make complexity vanish or reappear?), simple, brutal discriminator
- Enforced vocabulary (depth, leverage, locality, seam), end of fuzzy refactor conversations
- Reads ADR + CONTEXT.md before proposing, does not re-suggest refactors already rejected for cause
- The interactive 'grilling loop' after the chosen candidate, forces you to walk the design tree before coding
Limitations
- Requires a decent CONTEXT.md and ideally ADRs, otherwise suggestions are generic
- Non-trivial multi-file refactor, human review mandatory before merge
- No long-term skill API stability guarantee (distributed outside official Anthropic registry)
Best for
- Tech leads sensing their codebase leak (shallow modules everywhere, brittle tests) with no clue where to start
- Devs wanting to move from cosmetic refactor to argumented refactor (depth/leverage/locality)
- Agent-first teams wanting an AI-navigable codebase (precise vocabulary = AI-navigable)