improve-codebase-architecture is a check-up for a codebase. It finds places where code is hard to change, hard to test, or hard for an agent to find its way around, and suggests deepening opportunities: refactors (changes to the code's structure that keep what it does) that turn shallow modules into deep ones. A module is deep when a lot of behaviour sits behind a small interface; codebase-design teaches those words. The aim is code that's easy to test and easy for an AI agent to navigate.
When to use it
It's upkeep, not feature work. Run it whenever you have a spare moment, say between Specs on your FastAPI backend. The agent never starts it on its own: you type it.
It decides where to look before it looks. If you name a pain point ("the booking module"), it starts there. If not, it reads the recent commit history and looks first at the files that keep changing, because deepening pays off where future changes will land.
When not to use it
To design the shape of one module you've already chosen, use codebase-design. improve-codebase-architecture is the survey that finds the candidates; codebase-design is the bench where you design the chosen one.
To fix something that's broken right now, use diagnosing-bugs.
To sort out the project's own words ("is it a Booking or a Reservation?"), use domain-modeling.
What it needs to start
A codebase with some history. It first reads the project's GLOSSARY.md (the list of the project's own terms) and any ADRs in the area. An ADR, short for architecture decision record, is a short note in docs/adr/ saying what was decided and why. The Skill won't reopen those decisions unless the friction is real. Neither file has to exist.
What it creates
An HTML report in your computer's temp folder, so nothing lands in the repo. Each candidate gets its own panel: the files, the problem, the solution in plain English, the benefits, a before-and-after diagram, and a strength badge (Strong, Worth exploring or Speculative). A top recommendation closes the report. It doesn't propose interfaces yet: it asks which candidate you'd like to explore.
A grilling session on the candidate you pick, through grilling: constraints, dependencies, the shape of the deepened module, and which tests survive.
Glossary terms, added as decisions land, and an ADR if you want one: when you reject a candidate for a lasting reason, it offers to record it so future surveys don't suggest it again.
The candidate you pick becomes an idea you take into the main flow at grill-with-docs.
An HTML reportEach candidate gets its own panel
A grilling session on the candidate you pickthrough grilling
Matt's starting point is that an agent forgets everything between sessions. In his article "How To Make Codebases AI Agents Love" (updated 2026-02-26), he writes: "AI is not a super-powered developer. It's a new starter with no memory." He goes further: "Your codebase, way more than your prompt or your AGENTS.md file, is the biggest influence on AI's output." He adds that "You're spawning 20+ new starters a day to look at your codebase and make changes."
Code made of many small, tangled pieces is, in his words, "hard to navigate, hard to test, and hard to keep in your head."
Matt's picture of what an agent sees: disparate modules that can all import from each other. From aihero.dev, 30 October 2026.
In his AI Engineer Europe talk (2026-04-23), he shows a messy codebase next to a tidy one and asks: "So how do you turn a codebase that looks like this into a codebase that looks like that? Well, I've got a skill for that." He calls it "a set of steps that you can reusably do again and again."
Matt's AI Engineer Europe slide (2026-04-23): use /improve-codebase-architecture to deepen modules. From ai.engineer, 30 October 2026.
The idea is John Ousterhout's. Matt: "Deep modules comes from "A Philosophy of Software Design." The idea is simple: lots of implementation controlled by a simple interface."
Deep modules: big chunks of functionality behind simple interfaces, from Matt's article. From aihero.dev, 30 October 2026.
Matt doesn't copy the book. codebase-design, which this Skill uses for its words, rejects what it calls Ousterhout's measure, the ratio of implementation lines to interface lines. It says that measure "rewards padding the implementation. We use depth-as-leverage instead." The word "seam" comes from someone else again: codebase-design credits Michael Feathers.
Matt's Skill page (updated 2026-08-24) names two filters that keep the report focused.
The deletion test. codebase-design puts it this way: "Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep."
Hot spots first. Pull request #533 (merged 2026-07-13) says that before it, "the skill scans the whole repo evenly, which risks proposing deepenings in code nobody touches". The pull request's description says "read the last ~20 commit messages". But the SKILL.md as of 2026-10-29 says: "walk back a good stretch of the commit history".
The page also says what the Skill is not: "This makes it a survey, not a refactoring tool, so you can run it on a codebase you are not ready to touch yet."
Where it leads is what Matt calls grey box modules: "You own the interface. AI owns the implementation. Tests keep it honest."
A real example
On 2026-05-29 a user opened issue #274. They had liked the first version: "It was a convenient way to get a thorough analysis of improvements". Once grilling was added, they called it "borderline unusable". In their words, it "immediately proposes a single solution, and starts grilling you about it for usually 10's or 100's of questions." What they wanted was "to propose ideas in a shotgun blast so I can make the decision myself".
Another user asked whether you could just "tell the model not to grill you when invoking the skill".
The SKILL.md stops after the report: "Do NOT propose interfaces yet." Grilling starts only "Once the user picks a candidate". Matt's Skill page (2026-08-24) says this is "The design intent". But weaker models "skip straight to an interview about the first idea they had", and the page calls it "an open issue". The issue was closed 2026-10-06. For no grilling at all, the page says to ask: "don't grill me, just show the report".
Where it goes wrong
It rarely says "all fine". Issue #390 (2026-06-28) said it is "designed to output findings, so the framing nudges toward producing issues rather than concluding nothing's wrong." Matt's whole reply, the next day: "So you feel your codebase can no longer be improved?" His Skill page gives the fix: "If every candidate in a report is Speculative, the skill found nothing."
The report opens broken. Issue #651 (2026-07-23, still open; its body drafted by an AI agent, per its label): the report "opened as completely unstyled raw HTML — no Tailwind, no Mermaid rendering." The report loads its styling from the web, and a security hook, an offline machine or a network blocker can stop that. On 2026-10-24 another user hit it on a home network that blocks the styling site, and wrote that "The agent that wrote the report cannot see this". The Skill page's workaround: "ask for inline CSS and hand-built SVG diagrams instead of the CDN setup."
A clean refactor can change the screen. Issue #923 (2026-08-21, still open) says this Skill "(and implement) never look at the rendered app". After a report, the chain from this Skill through implement "deepened a module cleanly" with "types green, tests green, review clean", but it "had quietly changed the UI". Every step "inspects code, not pixels". It warns that shallow-looking pieces, such as "wrapper components, conditional-render branches, layout containers", can be the ones that matter on screen.
Too many candidates in one session. The Skill page: "Use one candidate per session." Otherwise the context window "fills with the report, the grilling, the domain-model edits and the code changes all at once."
An outdated claim about other tools. The Skill page says the exploration step names Claude Code's own tool, so other tools may skip it. The page, though updated 2026-08-24, still describes the wording from before pull request #781 (merged 2026-08-06). The SKILL.md as of 2026-10-29 is newer and decides. The changelog's entry for that pull request says it dropped "Claude Code's tool and agent-type names from the subagent-dispatch instructions". The current SKILL.md just says "spawn a sub-agent with a fresh context window".
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), pick the next thing you plan to build in api/, such as cancelling a booking.
Start from a clean git status.
Type /improve-codebase-architecture and give it a direction, as the Skill page suggests: "how can we make this change easy?" for the booking cancellation.
When the report opens, check the strength badges. If every candidate is Speculative, stop: it found nothing.
Run git status again. Nothing in the repo should have changed; the report sits in your temp folder.
Pick one Strong candidate and answer the grilling. If you reject it for a reason that will still hold next month, accept the ADR it offers.
Take that one decision into a Spec later, in a new session.
From snapshot/skills/improve-codebase-architecture/SKILL.md, line 64: “Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.”
From snapshot/skills/codebase-design/SKILL.md, line 107: “Depth as ratio of implementation-lines to interface-lines (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.”
From snapshot/skills/codebase-design/SKILL.md, line 63: “Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.”
