- Home
- Skills
- Code Quality & Review
- Architecture Improver: Untangle Codebases Safely
Works with the AI Agents you already use
Architecture Improver: Untangle Codebases Safely
Architecture Improver works like a careful staff engineer: measure, prioritise, refactor in tiny reversible steps.
Free
Architecture Improver: Untangle Codebases Safely
Example session with this skill installed
Our Node/TypeScript API has grown for 3 years and every change breaks something else. Find what's wrong with the architecture and fix the worst parts without changing behaviour.
- Read your context and instructions
- Compiled the architecture improver
Map
Express + TypeScript, Prisma, 412 files, 1,236 tests (baseline green, 2 skipped). Modules: routes/, services/, models/, utils/, jobs/.
Evidence
- Hotspots (12-month churn x complexity):
services/orderService.ts(1,840 lines, 214 commits),utils/helpers.ts(960 lines, imported by 131 files),routes/orders.ts madge --circular: 7 cycles, 5 throughutils/helpers.ts- Co-change:
routes/orders.ts+services/orderService.ts+jobs/invoice.tschange together in 63% of commits - 41 route handlers query Prisma directly
knip: 38 unused exports, 4 unused deps
Ranked findings
| # | Finding | Impact | Effort | Score |
|---|---|---|---|---|
| 1 | God orderService mixing pricing, invoicing, emails | 5 | M | 4.0 |
| 2 | utils/helpers dumping ground causing 5 cycles | 4 | S | 4.0 |
| 3 | Routes bypass services (Prisma in handlers) | 4 | M | 3.2 |
| 4 | Pricing rule duplicated in 3 places | 4 | S | 3.6 |
| 5 | Dead code & unused deps | 2 | S | 2.0 |
Target: feature folders features/{orders,invoices,customers}; rule: routes -> services -> repositories, never routes -> Prisma.
Done (you approved #2, #4, #5, #1)
- 23 characterisation tests added around order pricing/invoicing first
- 17 commits, each
refactor(scope): ..., tests green after every one helpers.tssplit and moved next to users -> cycles 7 -> 0- Pricing now in
features/orders/pricing.ts(single source) orderServicesplit intopricing,checkout,invoicing,notifications-> largest file 1,840 -> 390 lines- Removed 38 unused exports, 4 deps
- Added
dependency-cruiserrules to CI +docs/architecture.md+ ADR-001
Before / after
| Metric | Before | After |
|---|---|---|
| Cycles | 7 | 0 |
| Largest file | 1,840 | 390 |
| Files importing helpers | 131 | 0 |
| Tests | 1,236 | 1,259 green |
Next
#3 (routes -> services) touches 41 handlers: proposed as 4 PRs by feature. Start with invoices?
Connects securely to your tools. The creator never sees your data.
About this skill
Make your codebase easier to change, without a risky rewrite
"Clean up the architecture" usually ends in a huge diff, broken features or a fashionable pattern nobody needed. Architecture Improver works like a careful staff engineer: measure, prioritise, refactor in tiny reversible steps.
What it does
- Maps the codebase first: entry points, modules, dependencies, baseline tests; optional Mermaid diagram of the current state.
- Finds hotspots with data: git churn x complexity, dependency cycles, file sizes, co-change pairs, duplication, dead code (madge, dependency-cruiser, knip, radon, import-linter... whatever fits your stack).
- Diagnoses 15 architecture smells with evidence: god modules, circular deps, leaky layers, logic in controllers/handlers, shotgun surgery, utils dumping grounds, scattered config, hidden global state, inconsistent patterns and more.
- Ranked roadmap: impact x confidence / effort, plus a short target architecture with explicit dependency rules. You choose what to do.
- Safe refactoring: characterisation tests first where coverage is missing, then standard moves (extract, introduce boundary, invert dependency, parallel change, strangler fig), tests + typecheck green and one commit per step. Never mixes refactoring with behaviour changes.
- Guardrails: dependency rules in CI (dependency-cruiser, import-linter, ESLint, ArchUnit),
docs/architecture.md, ADRs. - Pragmatic: fits your stack and style; modular monolith over microservices unless the pain justifies it; prefers deleting code to abstracting it.
Includes
- SKILL.md workflow
- references/smells.md - 15 smells with evidence and fixes
- references/analysis-commands.md - tested commands for JS/TS, Python, Go, Java + git hotspot and co-change analysis
- references/refactorings.md - safe moves, commit discipline, ADR template
Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI and any SKILL.md-compatible agent.
Requires an existing test suite to guarantee behavior preservation. Git history access is needed for churn analysis. Works best on modular monoliths rather than distributed microservices.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
This skill has been used 10 times.
Trust & safety
Security scan
Security scan passed 10 days ago
- Free with an Agensi account
Requires