# Improve codebase architecture

> Scans a codebase for shallow modules, shows the candidates in a visual report, then interviews you about the one you pick.

Canonical: https://mikereams.com/ai/improve-codebase-architecture

Skill · Curated · Review & QA · updated 2026-10-29. Part of the [AI Library](https://mikereams.com/ai).

What you get: A report of the places where a refactor would put more behaviour behind a smaller interface, and a worked plan for the one you choose.

When to use it: When a codebase is hard to test or hard to find your way around, and before a larger refactor.

Ask for it like this: "Find the deepening opportunities in this codebase and show me the report."

Limits: My copy writes the report to the temp folder, not the repository, and gives you the path instead of opening it.

- Two skills, one card: codebase-design is the vocabulary the review speaks in (module, interface, depth, seam).
- I made the report self-contained. Upstream it loaded two scripts from CDNs, with a loose diagram setting, and opened the file with a shell command; mine loads nothing.
- I run it when the same files keep coming up in fixes. It starts from the commit history, so it looks where the change is.

Source: [mattpocock/skills](https://github.com/mattpocock/skills/tree/59db609/skills/engineering/improve-codebase-architecture) by Matt Pocock (MIT), reviewed at 59db609. Not hosted here. Also covers [codebase-design](https://github.com/mattpocock/skills/tree/59db609/skills/engineering/codebase-design), at the same commit.

Reviewed 2026-10-29.

Tags: architecture, refactoring, deep modules, testability