# Improve Codebase Architecture

> Audit the codebase's **architecture** and propose concrete improvements. This is structural work, not style nitpicking.

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

---


Audit the codebase's **architecture** and propose concrete improvements. This is structural work, not style nitpicking.

## Phase 1: Survey

Map the codebase before critiquing it.

- Entry points and data flow (where do requests/events enter, how do they propagate)
- Module boundaries and their dependencies (who imports whom)
- Layering: is there a clear separation between domain, application, infrastructure?
- State management: where does state live, who mutates it, what's the lifecycle?
- External integrations: databases, APIs, queues, filesystems
- Test structure: unit vs integration vs e2e, what's tested where

Report the map in 5-10 bullet points. If the codebase is huge, pick the subsystem most relevant to the user's request.

## Phase 2: Diagnosis

Check the mapped subsystem against every category below; silence on a category means checked-and-clean, not skipped.

Identify real architectural problems. Focus on these categories:

**Coupling issues**
- Modules that shouldn't know about each other but do
- Circular dependencies
- Shared mutable state across boundaries
- "God objects": one class/module that touches everything

**Cohesion issues**
- Modules that mix unrelated responsibilities
- Business logic leaking into controllers/routes/views
- Infrastructure concerns (DB, HTTP) mixed with domain logic

**Abstraction issues**
- Wrong abstractions: interfaces with one implementation, factories that don't vary, premature generalization
- Missing abstractions: repeated patterns that should be unified
- Leaky abstractions: implementation details bleeding through interfaces

**Boundary issues**
- Missing or porous boundaries between bounded contexts
- Direct DB access from everywhere instead of a repository/service
- Public APIs that expose internal types

**Testability issues**
- Hard-to-test code due to hidden dependencies, global state, or tight coupling to infrastructure
- Tests that know too much about implementation
- No seams to inject fakes or stubs

**Lifecycle / complexity debt**
- Dead code paths
- Feature flags that never shipped or never got cleaned up
- Duplicate implementations of the same thing
- Configuration sprawl

For each issue: **what** is wrong, **where** it lives (file:line), **why** it matters (what it costs the team), and **severity** (critical / high / medium / low).

## Phase 3: Recommendations

Propose changes in order of impact-to-effort ratio. For each:

- **Change:** concrete description (not "improve modularity", but "extract `PricingService` from `OrderController`")
- **Why:** what problem it fixes
- **Blast radius:** how many files/callers change
- **Risk:** what could break, how to mitigate
- **Test strategy:** how you'd verify the refactor didn't regress behavior
- **Scope:** small (1-2 files), medium (single subsystem), large (cross-cutting)

Group into:
- **Do now:** high impact, low risk
- **Plan for next sprint:** high impact, higher risk or effort
- **Don't do:** tempting but not worth it (explain why)

## Phase 4: Execution plan

If the user wants to proceed, pick the top 1-3 changes and outline the step-by-step execution. Prefer:

1. Characterization tests first (lock in current behavior)
2. Incremental refactors with tests passing at each step
3. One PR per logical change, not one mega-PR
4. Reversibility: each step should be independently mergeable and revertible

## Ground rules

- **Respect Chesterton's Fence.** A module that looks "weird" may encode a hidden constraint; ask why it exists before proposing to remove or rewrite it.
- **Aim for a codebase that's easier to change, not a textbook-pure one.**
- **Measure, don't guess.** If you claim something is slow or complex, show the evidence (profiler, cyclomatic complexity, churn data).
- **Justify every abstraction by a need that exists now, not a speculative future one.**

---

Target: $ARGUMENTS

If no target is specified, audit the whole codebase rooted at the current working directory.