Matt Pocock / improve-codebase-architecture
Can an agent tell you where your architecture actually hurts?
It can produce candidates. Choosing which ones matter is still your call.
What to remember
- Report first, change later. That order is what makes it safe to run.
- Scope it to a subsystem, because a whole repository report is too big to act on.
- Findings are candidates, not verdicts. Some will be wrong for reasons only your team knows.
- It pairs with grill-me when you want the reasoning stress tested before you commit.
01What it changes in practice
Architecture work usually fails for social rather than technical reasons: nobody can agree on where to start, so nothing starts. A concrete list of candidates with reasons attached turns that argument into a decision.
Presenting findings as a report also keeps the agent from doing the most dangerous thing available, which is refactoring several modules at once while you watch.
02Where it disappoints
It sees the code, not the history. Some awkward boundaries exist because of a constraint that is not written down anywhere, and the skill will confidently propose removing them.
Large reports also invite scope creep. The discipline of picking one candidate is entirely on you.
Install and first run
- Install it with the skills CLI from mattpocock/skills, published under MIT.
- Run it on one area rather than the whole repository, so the report stays reviewable.
- Pick one or two candidates. A list of thirty findings is a way of choosing nothing.
Questions people actually ask
- Does it change code automatically?
- It reports first and explores the candidates you select, rather than refactoring on sight.
- How large a codebase can it handle?
- Scope it to a subsystem. Whole repository reports tend to be too large to act on.
- Who maintains it?
- Matt Pocock, in his public skills repository under the MIT license.
Sources
Machine readable versions of this page