drvoss 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-docswhen design language and existing decisions must stay aligned