# Improve Codebase Architecture

> Scan codebase for deepening opportunities — refactors that turn shallow modules into deep ones.

- Skill: `y3owk1n/improve-codebase-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add y3owk1n/improve-codebase-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/y3owk1n/improve-codebase-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: y3owk1n (https://skillmd.com/u/y3owk1n)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/y3owk1n/improve-codebase-architecture

---


# Improve Codebase Architecture

Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

## Vocabulary

Use these terms exactly. Prefer: module, interface, implementation, depth, seam, adapter, leverage, locality.

| Term               | Meaning                                                                   |
| ------------------ | ------------------------------------------------------------------------- |
| **module**         | A unit of code with one responsibility                                    |
| **interface**      | The public surface a module exposes to callers                            |
| **implementation** | Everything behind the interface                                           |
| **depth**          | Ratio of implementation to interface — high = deep, low = shallow         |
| **seam**           | A place where two modules meet and can be swapped or tested independently |
| **adapter**        | A module that translates between two interfaces at a seam                 |
| **leverage**       | One interface serving many call sites                                     |
| **locality**       | Related behaviour concentrated in one place                               |

The **deletion test**: would deleting a module concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

## Process

### 1. Explore

**Scope before you scan: YAGNI.** Deepening pays off where future changes happen. Decide where to look before you look.

- If the user named a direction (module, subsystem, pain point), take it.
- Otherwise, walk back the commit history (`git log --oneline`) to find hot spots — files and areas that keep coming up. Let those paths pull your attention.

Read `prd/glossary.md`, `prd/architecture.md`, and `prd/decisions.md` for the area you're touching first.

Then walk the codebase. Note where you experience friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules **shallow** — interface nearly as complex as implementation?
- Where have pure functions been extracted just for testability, but real bugs hide in how they're called (no **locality**)?
- Where do tightly-coupled modules leak across their seams?
- Which parts are untested, or hard to test through their current interface?

### 2. Present candidates as a report

Ask the user: **HTML** (visual, opened in browser) or **Markdown** (terminal-friendly, version-controllable)?

#### HTML

Write a self-contained HTML file to the OS temp directory (`$TMPDIR`, fallback `/tmp`). Write to `<tmpdir>/architecture-review-<timestamp>.html`. Open it for the user (`open <path>` on macOS) and tell them the absolute path.

See `HTML-REPORT.md` for the full scaffold, diagram patterns, and styling guidance.

#### Markdown

Write to `<tmpdir>/architecture-review-<timestamp>.md` (`$TMPDIR`, fallback `/tmp`). Return the absolute path.

See `MD-REPORT.md` for the full template and diagram patterns.

#### Content (both formats)

Use `prd/glossary.md` vocabulary for the domain. If the glossary defines "Order," say "the Order intake module," not "the FooBarHandler."

If a candidate contradicts an entry in `prd/decisions.md`, only surface it when the friction is real enough to warrant revisiting. Mark clearly: _"contradicts the '{decision title}' decision, but worth reopening because…"_.

For each candidate, render a card with:

- **Files**: which files/modules are involved
- **Problem**: why the current architecture causes friction
- **Solution**: plain English description of what would change
- **Benefits**: in terms of locality and leverage, and how tests improve
- **Before / After diagram**: side-by-side, illustrating shallowness and deepening
- **Recommendation strength**: `Strong` (emerald), `Worth exploring` (amber), or `Speculative` (slate)

End with a **Top recommendation** section: which candidate to tackle first and why.

After the file is written, ask the user: "Which of these would you like to explore?"

### 3. Grilling loop

Once the user picks a candidate, dispatch `/grill` to walk the decision tree: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallise:

- **Naming a deepened module not in `prd/glossary.md`?** Add the term. Create the file lazily if it doesn't exist.
- **Sharpening a fuzzy term?** Update `prd/glossary.md` right there.
- **Boundary moved?** Update `prd/architecture.md`.
- **User rejects with a load-bearing reason?** Offer a `prd/decisions.md` entry: _"Record this so future reviews don't re-suggest it?"_ Only when the reason matters to a future explorer; skip ephemeral and self-evident ones.

## Completion

Done when: the report is written (HTML or Markdown), the user has picked a candidate, and the grilling loop has produced either a decision or a `prd/decisions.md` entry. Checkable: the report file exists in the expected path, and the user has confirmed which candidate to pursue.