---
name: review-codebase-architecture-prompt
description: A prompt that has the AI scan your codebase for shallow modules and tangled seams, rank "deepening" refactors that make code simpler to test and navigate, then grill you on the one you pick. Use when the user wants to improve codebase architecture, untangle messy code, plan a refactor, or make a repo easier for AI agents to work in.
license: MIT
metadata:
  category: coding-prompts
  tags: "architecture,refactoring,quality,testing,agents"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-10-31"
  status: published
  aliases: "improve-codebase-architecture,codebase-design"
  source_url: "https://github.com/mattpocock/skills/blob/a496f5513d4a4cf889bc48e189e579f4b0bdf6aa/skills/engineering/improve-codebase-architecture/SKILL.md"
  source_license: MIT
  copyright: "Copyright (c) 2026 Matt Pocock"
  original_author: "Matt Pocock (mattpocock/skills, 'improve-codebase-architecture' and 'codebase-design')"
  modified: "Adapted by TheSkillVault: one paste-in prompt; the codebase-design vocabulary is inlined in short form; the HTML report is optional (a Markdown report by default); the follow-up grilling loop is described inline; added safety and done-when sections."
  imported_on: "2026-10-31"
---

# Review codebase architecture (prompt)

The AI looks for places where the code is hard to understand or test. It proposes refactors that turn many shallow pieces into fewer "deep" modules: lots of behaviour behind a small, simple interface. Then it talks one of them through with you before touching any code.

## When to use
- The codebase feels tangled, and every change touches many files.
- You want a refactor plan, not a rewrite.
- AI agents keep getting lost in the repo or breaking things far from the change.

## Steps
1. Open your AI coding agent in the project folder and paste the prompt below.
2. Optionally name an area that hurts ("the checkout code"). Otherwise the AI picks hot spots from git history.
3. Read the report and pick one candidate. Answer the grilling questions.
4. Only then ask the AI to make the change, in small commits with tests.

## Prompt
```text
Review this codebase's architecture and propose "deepening" refactors. Do not change any code yet.

Vocabulary (use these words exactly):
- Module: anything with an interface and an implementation (a function, class, package or slice).
- Interface: everything a caller must know: types, rules, ordering, errors, config.
- Deep module: lots of behaviour behind a small interface. Shallow: interface nearly as complex as the code.
- Seam: the place where a module's interface lives and behaviour can be swapped.
- Adapter: a concrete thing plugged into a seam. One adapter = a hypothetical seam; two = a real one.
- Leverage: what callers gain from depth. Locality: change, bugs and tests concentrate in one place.
- Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through.
  If it reappears in many callers, it earns its keep.
- The interface is the test surface: tests should cross the same seam as callers.

1. Scope first. If I named an area, use it. Otherwise read `git log --oneline` for a good stretch
   and focus on files that change often. Read GLOSSARY.md and docs/adr/ if they exist;
   do not re-argue a recorded decision unless the pain is real, and say so.
2. Explore (with a sub-agent if you have them). Note where you feel friction:
   - understanding one idea means bouncing between many small modules
   - shallow modules, or pure functions pulled out only for tests while bugs hide in the callers
   - tightly coupled modules leaking across seams
   - code that is untested or hard to test through its interface
3. Write a report to a temp file outside the repo (Markdown, or self-contained HTML if I ask).
   For each candidate give: Files, Problem, Solution (plain English), Benefits (leverage,
   locality, better tests), a before/after sketch, and a strength: Strong, Worth exploring
   or Speculative. Use the project's own domain words for names. End with your top pick and why.
4. Do not design interfaces yet. Ask me: "Which of these would you like to explore?"
5. When I pick one, grill me in rounds about constraints, dependencies, the new module's shape,
   what sits behind the seam and which tests survive. Give a recommended answer for each question.
   Add any new domain term to GLOSSARY.md. If I reject a candidate for a lasting reason,
   offer to record it as an ADR so future reviews skip it.

FOCUS AREA (optional): {{e.g. "the billing code" or leave blank}}
```

## How to adapt
- Want visuals? Ask for "an HTML report with before/after diagrams" (Mermaid works well).
- Big monorepo? Name one package as the focus area.
- Works with any stack and any coding agent that can read files and run git.

## Gotchas
- A refactor plan is not permission to refactor. Keep step 4: no code until you pick.
- Writing the report inside the repo adds noise to git. Keep it in a temp folder.
- The AI reads your whole codebase. Make sure secrets live in ignored .env files, not in source, before you start.

## Done when
- You have a ranked list of candidates with a top recommendation.
- One candidate has been grilled into an agreed design, and new terms or ADRs are written down.

## Example prompt
"Our API folder is a mess. Review the codebase architecture and suggest the refactors that would help most."

---
Adapted from "improve-codebase-architecture" and "codebase-design" in mattpocock/skills by Matt Pocock (MIT). See LICENSE.txt.