Generic architecture review produces generic output. “Consider extracting this into a service.” “This class has too many responsibilities.” These observations are technically defensible and practically useless — they ignore the domain, the history of the decisions, and the constraints that produced the current shape.
improve-codebase-architecture runs a different kind of review. It reads the domain model before reading the code.
What it reads
Before analysing structure, the skill builds context from:
- Entity and aggregate names — what the domain calls things
- ADRs — recorded decisions and their rationale
- Module and package boundaries — what was deliberately separated
- Naming patterns — where naming is consistent and where it drifts
Only after that does it look at structural issues.
What the review targets
- Concepts that exist in the domain but have no clear home in the codebase
- Boundaries that exist in the code but don’t map to domain boundaries
- Naming drift — where code names diverge from domain names
- Coupling that crosses a boundary that an ADR says should be hard
- Missing abstractions — patterns repeated in multiple places with no shared name
Usage
/improve-codebase-architectureNo arguments required. Run from the project root. If ADRs exist (typically in docs/adr/ or docs/decisions/), the skill finds and reads them. If they don’t, it derives decisions from naming and structure.
The difference from generic refactor
A generic refactor suggestion works from code structure alone. It sees a large class and recommends splitting it. It sees duplication and recommends extraction. These are pattern matches against code shape.
Domain-informed review sees a large class and asks whether it’s large because it was built wrong or because the domain concept it represents is genuinely large. It sees duplication and asks whether the two duplicated sections represent the same concept or two concepts that currently look identical but will diverge.
The outputs are different. One produces smaller classes. The other produces a codebase that’s easier to reason about in domain terms — which is the property that actually reduces maintenance cost.
When it’s most useful
- Before a significant new feature that touches multiple modules
- After a period of rapid delivery where architectural consistency was deprioritised
- When onboarding reveals that the codebase is hard to explain to new contributors