# Improve Codebase Architecture

> Use when: propose structural improvements to a codebase without rewriting it wholesale.

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

---


Goal: identify high-leverage architecture changes and sequence them safely.

Use for:
- tangled dependencies, leaky boundaries, or scattered logic
- modules that are hard to change or test in isolation
- recurring bugs that trace back to structure, not code

Workflow:
1. Map the current modules, boundaries, and data flow.
2. Locate the pain: what change is consistently hard or risky.
3. Name the architectural cause, not the surface symptom.
4. Propose a target structure with clearer boundaries.
5. Sequence the move as small, independently shippable steps.
6. Define how each step is verified before the next.

Look for:
- deep modules with simple interfaces vs. shallow leaky ones
- cyclic dependencies and god objects
- business logic mixed with I/O or framework code
- duplicated knowledge across layers

Rules:
- justify each change by a concrete pain it removes
- prefer incremental migration over big-bang rewrite
- keep public behavior stable unless change is the goal
- do not add abstraction without a second real use