A hotspot keeps changing
Start with recent history to investigate the area causing recurring changes.
Improve Codebase Architecture by Matt Pocock
Use Improve Codebase Architecture by Matt Pocock to survey the parts of a repository that are difficult to change or test. Review a visual report of candidate module improvements, choose one grounded in actual friction, and explore its design before authorizing a refactor.
Install and get started
Choose your agent to see how to get started. In Floatboat, copy a request that asks the agent to read the original instructions. Other options show the Skill installation command or the publisher’s native setup steps.
Choose an agent
Start in Floatboat
Copy the request into a Floatboat conversation
Read the original Improve Codebase Architecture instructions at https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/SKILL.md. Explain its purpose, required tools, and installation options, then help me use it.Let the agent read the original instructions and check how to use them in your environment.
Download Floatboat ↗Try this request
Survey the order-import subsystem for architecture friction. Respect existing ADRs, show candidate improvements first, and do not refactor until I choose one.
About Improve Codebase Architecture
Improve Codebase Architecture is a user-invoked survey in Matt Pocock’s collection. It examines a named area or recent change hotspots for shallow modules, leaking seams, and testing friction. The agent presents candidate improvements in an HTML report with affected files, before-and-after views, and recommendation strength. You choose which candidate deserves further discussion; the source does not begin by redesigning every interface. Its later interview uses grilling, codebase-design, and domain-modeling, consulting the project glossary and architectural decisions. This is a way to identify and examine worthwhile changes, not proof that a proposed architecture is better or permission to rewrite the repository.
Use Cases for Architecture Reviews
Explore architecture questions tied to recurring development friction. Survey a frequently changed module, investigate why useful behavior is difficult to test, or examine scattered responsibilities before selecting a candidate whose interface and implementation can be improved with a specific, reviewable design.
Behavior is hard to test
Look for an interface that exposes too little useful behavior or forces tests into internals.
Understanding crosses many files
Examine whether scattered modules create real navigation and maintenance costs.
How to Explore Architecture Improvements
Install the related collection skills and provide a subsystem or concrete pain point. Let the agent survey the relevant code and existing decisions, review its visual candidate report, and choose one opportunity for a design interview before planning implementation and validation.
- 01
Set the survey scope
Name an area or pain point and provide existing domain docs. Let recent change history inform the scope when no area is specified.
- 02
Review the candidate report
Inspect the affected files, friction, proposed direction, and visual comparisons. Distinguish strong recommendations from speculative ones.
- 03
Explore one selected design
Choose a candidate for the dependent-decision interview. Agree the intended interface, preserved behavior, and validation before refactoring.
Explore More Agent Skills
Read another Skill guide and check its original source before using it.
Improve Codebase Architecture FAQ
Does this Skill refactor everything it finds?
No. It first presents candidate improvements and asks which one you want to explore. Implementation is a later task with its own scope and checks.
What is a deepening opportunity?
It is a proposal to hide meaningful complexity behind a simpler, useful interface. The value must be explained through actual callers, locality, or testability rather than abstraction alone.
Which companion Skills are required?
The current source references codebase-design, grilling, and domain-modeling. Install the collection so those references can be resolved by the host agent.
What does the report contain?
It describes affected files, architectural friction, possible changes, benefits, visual comparisons, and recommendation strength. The source writes a separate HTML file in the OS temporary directory.
How are existing ADRs handled?
The survey reads relevant decisions first. A conflicting proposal should identify the conflict and explain why observed friction might justify reopening it.
Does the workflow need subagents?
The documented exploration uses a subagent, and interface alternatives can also use parallel agents. A host without those capabilities cannot reproduce every step unchanged.