gs-improve-codebase-architecture
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.
The project's domain model informs this skill, and it builds on a shared design vocabulary:
-
Use
gs-codebase-designwhen it is installed, 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 means a hypothetical seam, two means a real one"). Without it, use these definitions:- Module: anything with an interface and an implementation, from a function to a package.
- Interface: everything a caller must know to use the module: types, invariants, ordering, error modes, configuration, and performance.
- Depth: how much behaviour a caller can exercise per unit of interface. A deep module hides a lot behind a small interface. A shallow module's interface is nearly as complex as its implementation.
- Seam: the place where a module's interface lives, where behaviour can change without editing that place.
- Adapter: a concrete thing that satisfies an interface at a seam.
- Leverage: what callers get from depth, more capability per unit of interface.
- Locality: what maintainers get from depth, change and bugs concentrated in one place.
- The deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it earned its keep.
Use these terms exactly in every suggestion. Don't drift into "component," "service," "API," or "boundary."
-
When the project has a domain glossary (
GLOSSARY.md), its terms name good seams. When it has ADRs indocs/adr/, they record decisions this skill should not re-litigate. A project may have neither.