Survey costly code structure, present refactoring candidates visually and explore the option you choose.
Install and prepare
Run the following in your project terminal, then use the prompt below in Claude Code. This installs editable, project-scoped skill files.
npx skills@latest add mattpocock/skills --skill improve-codebase-architecture --skill codebase-design --skill grilling --skill domain-modeling --agent claude-code
For Codex, replace claude-code with codex in the command and /improve-codebase-architecture with $improve-codebase-architecture in the prompt. With the complete Claude Code plugin, select /mattpocock-skills:improve-codebase-architecture instead; avoid installing the same skills twice.
Install codebase-design, grilling and domain-modeling alongside it. Open the repository and identify frequently changed, hard-to-understand or hard-to-test areas. Existing ADRs should constrain the discussion.
Your first task
Adapt the scenario and paths to your project, then enter this in the agent conversation:
/improve-codebase-architecture
Every coupon change touches checkout, orders and marketing. Focus on that call chain, show before/after diagrams and benefits for refactoring candidates, and let me choose one before detailed design.
Work through the task
Set the survey scope
Use recent Git changes and a concrete pain point to focus the survey rather than scanning every file equally. In the coupon example, investigate why one rule spans three directories and whether tests require extensive internal mocking to reach it.
Compare what callers must understand
A candidate should explain which rules could sit behind a smaller, more stable interface and what callers would no longer need to know. Combining files is not the goal. Moving code without reducing the knowledge required by callers may not justify a refactor.
Choose from the visual report
The temporary HTML report covers files, problems, proposals, before/after diagrams and recommendation strength. Choose one candidate before the interview explores interfaces, tests and constraints. Settled domain concepts can enter the glossary, and lasting trade-offs can become ADRs.
Check the result
Expect a viewable report and a clear next decision: pursue one refactor, validate its value or leave it for now. The proposal should explain change costs and testing improvements, not merely make directories look tidier.
Common questions
Will it rewrite the project immediately? It first presents candidates and then explores your choice.
The report looks unstyled. Its CDN resources may not load offline.
Every run finds more ideas. Judge them by actual maintenance costs and upcoming changes rather than aiming for zero suggestions.
A report card should explain what callers no longer need to know
Suppose permission checks are scattered across API handlers, middleware, and pages, so each new role needs three edits. Ask: “Use improve-codebase-architecture to investigate recent permission-rule changes without modifying code. For each candidate, show which callers know too much about roles, what smaller interface might hide that detail, and which tests could move from internal mocks to a public boundary.” Have it inspect recent commits and actual call paths before reading the HTML report.
A useful card says what callers can stop knowing, not just “create PermissionsService.” If removing a shallow module merely copies its conditionals into callers, it fails the deletion test. Choose one card before discussing implementation. Code edits or dozens of cleanup items unrelated to recent work indicate the survey drifted.
Compare the real UI before and after
If the proposed boundary change touches UI components, capture the real page before editing in normal, loading, empty, and error states. Compare the same inputs and interactions afterward. In one reported use of this skill, types, tests, and code review were green while a conditional-render branch and prop passthrough disappeared. Treat preserved user-visible behavior as an acceptance condition alongside cleaner module dependencies.