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.
This command is informed by the project's domain model and built on a shared design vocabulary:
- Run the
/codebase-designskill 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.mdgives names to good seams; ADRs indocs/adr/record decisions this command should not re-litigate.
User clarifications (Cursor)
When you need a discrete decision with a small set of clear options (about 2–6), prefer the AskQuestion tool so the user gets structured choices. Ask one decision at a time when this skill already sequences questions that way.
If AskQuestion is unavailable in the current environment, ask the same choices in ordinary chat (same options, same ordering).
Use plain chat (not forced multiple-choice) when the answer is inherently free-form—for example pasted logs, a paragraph describing a custom tracker workflow, or an open-ended design explanation.
If a question can be answered by exploring the codebase, explore the codebase instead.