Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Architecture Improver: Untangle Codebases Safely

    3

    Architecture Improver works like a careful staff engineer: measure, prioritise, refactor in tiny reversible steps.

    Free

    10 uses5.0 (1 review)
    Architecture Improver: Untangle Codebases Safely

    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 through utils/helpers.ts
    • Co-change: routes/orders.ts + services/orderService.ts + jobs/invoice.ts change together in 63% of commits
    • 41 route handlers query Prisma directly
    • knip: 38 unused exports, 4 unused deps

    Ranked findings

    #FindingImpactEffortScore
    1God orderService mixing pricing, invoicing, emails5M4.0
    2utils/helpers dumping ground causing 5 cycles4S4.0
    3Routes bypass services (Prisma in handlers)4M3.2
    4Pricing rule duplicated in 3 places4S3.6
    5Dead code & unused deps2S2.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.ts split and moved next to users -> cycles 7 -> 0
    • Pricing now in features/orders/pricing.ts (single source)
    • orderService split into pricing, checkout, invoicing, notifications -> largest file 1,840 -> 390 lines
    • Removed 38 unused exports, 4 deps
    • Added dependency-cruiser rules to CI + docs/architecture.md + ADR-001

    Before / after

    MetricBeforeAfter
    Cycles70
    Largest file1,840390
    Files importing helpers1310
    Tests1,2361,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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    5.0
    1 review
    5
    1
    4
    0
    3
    0
    2
    0
    1
    0

    This skill has been used 10 times.

    Trust & safety

    Security scan

    Security scan passed 10 days ago

    • Free with an Agensi account

    Requires

    madge
    Node.js
    dependency-cruiser
    depcruise
    pydeps
    uv (Python tool runner)
    import-linter
    Python
    knip
    radon
    vulture
    jscpd
    Git
    uv (Python tool runner)

    Permissions

    Terminal / Shell
    Write Files
    Network Access
    Environment Variables
    Listed10 days ago
    Updated5 days ago

    What's inside

    Frequently Asked Questions

    The skill correlates Git history with cyclomatic complexity to identify 'hotspots'—areas of code that change frequently but are difficult to maintain. This ensures you invest time refactoring code that actually impacts developer velocity rather than stable, low-churn files.

    Yes, the skill is designed to work with any language or framework provided there is a functioning test suite and a linter. It natively supports boundary enforcement tools like dependency-cruiser (JS/TS), ArchUnit (Java), and import-linter (Python).

    Unlike generic prompts, this skill uses a 'strangler fig' approach, making tiny, behavior-preserving changes followed by immediate testing. It avoids 'big bang' rewrites, ensuring your codebase remains deployable and the test suite stays green at every step.

    No, the skill requires an existing test suite to validate its changes. While it can identify architectural flaws without tests, it will decline to perform automated refactoring if it cannot verify that behavior remains unchanged.

    Beyond the code changes, the skill generates dependency graphs, a ranked technical debt roadmap, and CI-ready linting rules to prevent future architectural regression. It also produces Architecture Decision Records (ADRs) to document why specific changes were made.

    New in Code Quality & Review