# Improve Codebase Architecture

> Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

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

## Glossary

Use these terms exactly in every suggestion. Full definitions are in [LANGUAGE.md](LANGUAGE.md).

- Module: anything with an interface and an implementation.
- Interface: everything a caller must know to use the module correctly.
- Implementation: the code inside.
- Depth: leverage at the interface. Deep means high leverage; shallow means the interface is nearly as complex as the implementation.
- Seam: where an interface lives; a place behavior can be altered without editing in place.
- Adapter: a concrete thing satisfying an interface at a seam.
- Leverage: what callers get from depth.
- Locality: what maintainers get from depth.

Key principles:

- Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across many callers, it was earning its keep.
- The interface is the test surface.
- One adapter means a hypothetical seam. Two adapters means a real seam.

## Process

### 1. Explore

Read the project's domain glossary and any ADRs in the area first. Then inspect the codebase organically and note where understanding creates friction:

- Where does understanding one concept require bouncing between many small modules?
- Where are modules shallow?
- Where have pure functions been extracted only for testability, while real bugs hide in how they are called?
- Where do tightly-coupled modules leak across seams?
- Which parts are untested, or hard to test through their current interface?

Apply the deletion test to anything suspected of being shallow.

### 2. Present Candidates

Present a numbered list of deepening opportunities. For each candidate include:

- Files: which files/modules are involved.
- Problem: why current architecture causes friction.
- Solution: plain-English description of what would change.
- Benefits: explain locality, leverage, and how tests would improve.

Use `CONTEXT.md` vocabulary for the domain and [LANGUAGE.md](LANGUAGE.md) vocabulary for architecture. If a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting that ADR.

Do not propose interfaces yet. Ask: "Which of these would you like to explore?"

### 3. Grilling Loop

Once the user picks a candidate, walk the design tree: constraints, dependencies, the shape of the deepened module, what sits behind the seam, and what tests survive.

Side effects happen inline as decisions crystallize:

- If naming a deepened module after a concept not in `CONTEXT.md`, add the term using [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md).
- If sharpening a fuzzy term, update `CONTEXT.md` immediately.
- If the user rejects the candidate with a load-bearing reason, offer an ADR using [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
- If exploring alternative interfaces, use [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).