Improve Codebase Architecture

Use this skill when local cleanup is not enough and the problem is architectural shape: too many shallow modules, leaky seams, or a design that is hard to test through the public interface.

When to Use

• The codebase is correct enough to run, but hard to extend safely
• Understanding one concept requires bouncing across too many tiny modules
• Tests are brittle because the interesting behavior leaks across current seams
• A refactor candidate needs architectural reasoning before code changes start

When NOT to Use

Instead of improve-codebase-architecture	Use
You only need a bigger-picture map of one area	zoom-out
The architecture is fine and you just need safe cleanup	refactor-clean
You are defining a new feature before coding	spec-driven-development

Prerequisites

• Access to the project's README, architecture docs, glossary, ADRs, or equivalent guidance
• Enough codebase access to inspect callers, collaborators, and tests
• Willingness to stop at a candidate list first instead of jumping straight into rewrites

Working Vocabulary

Use these terms consistently while reviewing the design:

Term	Meaning
Module	Any unit with an interface and implementation: function, class, package, or slice
Interface	Everything a caller must know: types, invariants, ordering, config, and error modes
Depth	How much behavior a module hides behind a small interface
Seam	The place where behavior can change without editing every caller

Workflow

1. Load the project's language first

Read the domain vocabulary and architecture decisions before suggesting anything. Prefer the project's own names for subsystems and workflows instead of inventing new terminology.

1-A. Decide where to look before scanning

If the user already named a subsystem, workflow, or module, keep the review there. If they did not, use recent commit, PR, or change history to identify which areas are actively changing and scope the architectural review to those active areas first rather than surveying the whole repository. Deepening architecture pays off most where future changes are likely to land; stable untouched areas are a lower priority.

2. Explore for architectural friction

Look for places where:

• the interface is nearly as complicated as the implementation
• behavior is scattered across many pass-through modules
• tests mostly exercise wiring because the real logic has no stable seam
• bug fixes require touching several files that conceptually belong together

Apply a quick deletion test: if deleting the module would only move the same complexity to every caller, it is earning its keep; if complexity largely disappears, the module is probably shallow.

3. Present deepening opportunities

Return a short numbered list of candidates before proposing exact interfaces. Use this shape:

1. **Candidate:** Order intake module
   - **Files:** `src/...`
   - **Problem:** Callers know too much about validation and retries
   - **Suggested seam:** Consolidate workflow behind one module
   - **Why it helps:** Better locality, simpler tests, fewer cross-file edits

4. Grill the chosen candidate

Once the user picks a candidate, walk the design tree with them:

• what behavior belongs behind the new seam
• what stays outside
• which dependencies become adapters
• what the new test surface should look like
• whether any ADR or glossary term needs updating

Do not rewrite half the codebase in one jump. The goal is one clear architectural move.

5. Capture the decision

When the direction is clear, record it in the right durable place:

• ADR for a structural decision that future contributors must not re-litigate
• spec or plan for an approved refactor
• issue or backlog item if the work is valuable but deferred

Examples

Example: Thin pass-through module

If three controllers each validate, transform, and retry the same workflow with slightly different glue code, propose a deeper module that owns the workflow and leaves controllers with parameter collection plus response mapping.

Example: Testability problem

If a feature only seems testable through large integration tests because the important logic is spread across helpers and callers, propose a seam that centralizes decisions and makes public behavior testable in one place.

Common Rationalizations

Rationalization	Reality
"We should just rewrite the whole area"	Rewrites hide the real design problem. Find one load-bearing seam first.
"Small files mean good architecture"	Splitting code is not the same as creating depth. Shallow modules still leak complexity.
"We can decide the interface later"	The interface is the real design work; skipping it postpones the hard part.

Red Flags

• Proposed modules are named after implementation details instead of domain concepts
• Every candidate requires a sweeping rewrite instead of an incremental move
• The same ADR conflict appears, but no one states whether it should be reopened
• Tests get harder because the design introduces more wiring than leverage

Verification

• The review produced a short candidate list before detailed design work
• Each candidate names affected files, the current problem, and the expected leverage
• The chosen direction defines a clearer seam and a simpler test surface
• Any ADR or glossary conflict is called out explicitly instead of ignored

Tips

• Use the project's real vocabulary; architecture advice is weaker when the language drifts
• Prefer one strong candidate over a long generic list
• Pair this skill with grill-with-docs when design language and existing decisions must stay aligned