01
It starts by itself
weekly architecture review. Runs in Claude Code routine.
- ↻ weekly architecture review
0 9 * * 1
Matt Pocock · 1.2M installsAI Hero · ex-Vercel · Total TypeScriptImprove Codebase Architecture skill
Runs by itself, every Monday.
Code that gets easier to change each week.
Install the Improve Codebase Architecture skill and make it a habit: follow https://gethabit.dev/skills/mattpocock/improve-codebase-architecture.md
- 1Copy
- 2Paste into Claude Code, Codex or Cursor
- 3It runs by itself
1.2M installs300K starsMIT licenceSource on GitHub ↗
Improve Codebase Architecture
by Matt Pocock · 1.2M installs
The skill
Finds messy parts of your code and helps you make them simpler.
Only when you ask.
Cleaner code
Code that gets easier to change each week. Less time lost on hard-to-test spots.
↻ Runs by itselfevery Monday
How the habit works.
You don't have to.
When does it start? How does it check its work? What does it remember?
One run, step by step.
Then it stops.
Stops after one report and one picked candidate per run.
- 01
Load the vocabulary
Your agent calls the codebase design skill for terms like module, seam, depth and leverage.
- 02
Read the domain
It reads GLOSSARY.md and the ADRs in docs/adr/ so it does not reopen settled decisions.
- 03
Find hot spots
Unless you named an area, it walks git log --oneline to see which files change most.
- 04
Explore
A sub-agent walks the code, notes friction and applies the deletion test to suspect modules.
- 05
Write the report
It writes a self-contained HTML report with one card and before/after diagram per candidate.
- 06
Ask you
It opens the report and asks which candidate you want to explore.
- 07
Grill the pick
It calls the grilling skill on your choice and the domain modeling skill to keep GLOSSARY.md current.
- 08
Offer an ADR
If you reject a candidate for a lasting reason, it offers to record that as an ADR.
What it may do.
Nothing more.
It writes only in its own folder and asks you before anything goes out.
- Writes only in$TMPDIR/architecture-review-*.html, GLOSSARY.md, docs/adr/**, loops/architecture-deepening-loop/**
- Talks tono outside service
- Sendsnothing
- Your OKIt asks you before anything goes out.
Is it for you?
Use it when it fits.
Read both lists. If the left one sounds like you, the Improve Codebase Architecture skill helps.
Use it when
- ✓ Your code feels hard to change
- ✓ Tests are hard to write
- ✓ You want a refactor plan
Skip it when
- – The codebase is tiny
- – You need a quick bug fix
Improve Codebase Architecture skill, answered.
Does the report land in my repo?
No. It goes to the OS temp directory, with a new file each run.
Which other skills does it use?
Codebase design for the vocabulary, grilling for the interview and domain modeling for the glossary.
Will it propose new interfaces in the report?
No. Interfaces come only after you pick a candidate and the grilling starts.
How do I install the Improve Codebase Architecture skill?
Copy the prompt at the top into your agent. It installs the skill from mattpocock/skills and sets up the habit. Or run npx skills add mattpocock/skills --skill improve-codebase-architecture.
Is the Improve Codebase Architecture skill free?
Yes. It is published under MIT. Habit is free too.
Improve Codebase Architecture. Now as a habit.
Install the Improve Codebase Architecture skill and make it a habit: follow https://gethabit.dev/skills/mattpocock/improve-codebase-architecture.md
All Matt Pocock skills →More code skills →
Works in
- Claude Code
- Codex
- Cursor
- ChatGPT
- Claude app
Made by Matt Pocock, published under MIT. Habit links to the original and never changes it. Is this your skill?