# Improve Codebase Architecture

> Use when improving codebase architecture, reducing coupling, or increasing cohesion

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

---


# Improve Codebase Architecture

Analyze and improve codebase architecture by identifying opportunities for deeper modules, better seams, and reduced coupling.

## Process

### 1. Map the current architecture
- Identify modules (packages, directories, classes)
- Document entry points and dependencies
- Measure module depth (interface vs implementation ratio)

### 2. Identify problems
- Shallow modules (interface nearly as complex as implementation)
- Tight coupling between unrelated concerns
- God modules that do too much
- Missing seams (should be separable but aren't)

### 3. Report with an HTML report
Generate a structured report with the current architecture, identified issues, and specific recommendations. Present both a quick summary inline and a detailed HTML report.

### 4. Prioritize improvements
Rank by impact: which changes give the most leverage for the least risk?

## Common Pitfalls

- **Analyzing without a clear baseline**: Run the analysis tools before making any changes to establish the baseline metrics.
- **Focusing only on structure, not behavior**: Architecture is about both. A structurally clean module that is hard to use or test is not an improvement.
- **Refactoring without tests**: Architecture improvements without test coverage are risky. Ensure the critical paths are tested before restructuring.

## Verification Checklist

- [ ] Baseline architecture metrics gathered
- [ ] Deepening opportunities identified
- [ ] Coupling points documented
- [ ] Specific recommendations provided
- [ ] Changes tested and verified