Skip to main content
skill CX Codex

improve-architecture · rohitg00 — Claude Code skill: diagnose and refactor

improve-architecture audits code structure, identifies tangles in boundaries and dependencies, and proposes a ranked list of minimal moves that relieve the strain—no rewrite, only a plan you approve first.

MIT ★ 2,966 updated 2026-09-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What improve-architecture does

The skill maps an area of your codebase, finds load-bearing problems in its shape, and lists the smallest structural moves that improve it. It starts by charting the current layout: entry points, modules, data flow. Then it hunts for real strain—god modules everything depends on, leaky boundaries, duplicated logic that drifts, cyclic dependencies, seams in the wrong places—and ranks moves by leverage: pain relieved per unit of work. For significant changes, it suggests a decision record in docs/decisions/.

The output is a prioritized plan you review before any code moves. The skill diagnoses and recommends; it does not rewrite on its own. Each proposed move solves a named problem, not a taste preference.

What it helps with

  • find modules that become bottlenecks because everything imports them
  • spot duplicated logic that diverges across implementations
  • break circular dependencies between components
  • align module boundaries with the shape of your domain
  • move seams so the codebase bends where it changes

Example prompts for the agent

  • Audit the auth subsystem in src/auth/ and identify the three highest-leverage moves to improve its structure
  • Everything in our system pulls from utils—how do we untangle and split it?
  • Review the data models and propose minimum shifts to draw a clean boundary between business logic and storage layers

How to install improve-architecture

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill improve-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/improve-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/improve-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about improve-architecture

How do I install improve-architecture in Claude Code?

Run these in order: /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow, then npx skills add rohitg00/pro-workflow --skill improve-architecture -a claude-code. Configuration lands in ~/.claude/skills/improve-architecture/SKILL.md.

What does the improve-architecture skill do?

It maps your code structure, finds strain points like tangled boundaries and duplication, and gives you a ranked list of the smallest moves that relieve them. It diagnoses and proposes; it does not rewrite.

Do I need tests before using the skill?

Not always. The skill recommends; you decide which moves to make. For large structural changes, it often suggests landing behind green tests first, so refactors are safer.

Source text

SKILL.md · MIT
---
name: improve-architecture
description: Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture.
user-invocable: true
---

# improve-architecture

Invest in the shape of the system a little at a time rather than paying for a
rewrite later. This skill diagnoses and proposes; it does not rewrite on its own.

## Method

1. **Map first.** Get the current shape before judging it - entry points,
   modules, data flow, who calls whom. Reuse `module-map` for the one-screen
   view; do not skip to opinions.
2. **Find the strain.** Look for the load-bearing problems, not style nits:
   - God modules that everything imports and nothing can change safely.
   - Leaky boundaries - a module reaching into another's internals instead of
     its surface.
   - Duplicated logic that drifts (the same rule implemented three ways).
   - Wrong seams - the code is split where it does not bend and fused where it
     does.
   - Cyclic dependencies.
   - A shape that fights the domain (see `domain-modeling` - boundaries in code
     should track boundaries in the language).
3. **Propose the smallest move.** For each problem, the least change that
   relieves it: extract a boundary, collapse a duplicate, invert a dependency,
   move a seam. Prefer a sequence of safe steps over one big cut.
4. **Rank by leverage.** Order the moves by pain relieved over effort. Say which
   are safe now and which need a test net first (pair with `tdd`).
5. **Record the big calls.** For a structural change a future reader would
   question, write a decision record in `docs/decisions/NNNN-slug.md`: context,
   choice, alternatives rejected, why.

## Guardrails

- Diagnose, do not rewrite. The deliverable is a plan the user approves before
  any code moves.
- No churn for taste. A move must relieve a named strain; "cleaner" is not a
  reason.
- Three similar lines beat a premature abstraction - do not trade duplication
  for indirection unless the duplication actually drifts.
- Keep behavior fixed. Structural moves are refactors; land them behind green
  tests.

## Output

A prioritized list: each item is the problem, the smallest move, the risk, and
whether it needs a test net first. Plus decision records for the big moves. No
code changes until the user picks what to do.

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar skills

All skills for Code review and refactoring →

improve-architecture by other authors comes first.

improve-architecture daveebbelaar The improve-architecture Claude Code skill reviews a macOS Swift codebase and plans refactors that preserve existing behavior. It activates before a major feature, at a milestone, or when bugs keep returning in one area. CX Codex +1 1,000installs architecture-optimization wondelai The architecture-optimization Claude Code skill guides architecture, code-quality, and performance work on a live codebase. It records decisions and measurements across eight phases. CX Codex +1 1,700installs improve-code-quality wondelai improve-code-quality — a skill for Claude Code and Codex guides untested code toward production stability. It runs an interactive nine-phase workflow and records every milestone in local markdown files. CX Codex +1 2,700installs improve owainlewis The improve Claude Code skill simplifies existing code while preserving its behavior. It targets duplication, dead code, unclear names, and needless abstractions. CX Codex +1 372installs platform-architecture-analyze forcedotcom platform-architecture-analyze audits Salesforce DX projects against the Salesforce Well-Architected framework. Generates an evidence-backed health report without editing code. CX Codex +1 3,100installs principal-engineering riekelt principal-engineering enforces core engineering discipline for AI agents: mandates pre-change checkpoints, bans silent error suppression, and requires evidence from real code. CX Codex +1 25,700installs guarding-architecture riekelt guarding-architecture enforces system boundaries by turning structural invariants into breaking build tests. Useful when code crosses module limits or adds unwanted cross-package imports. CX Codex +1 25,600installs

From the same set83

The whole set →
commit Runs project checks, reviews staged changes, and creates a focused git commit. Use it when a change is ready to be recorded. CX Codex +1 ★ 2,966repo stars mcp-audit mcp-audit analyzes connected MCP servers for token overhead, redundancy, and unused configurations. Run when sessions slow down or before connecting a new server. CX Codex +1 ★ 2,966repo stars tdd tdd guides Claude Code through a strict test-driven development loop: write a failing test, pass it with minimal code, and clean up. CX Codex +1 ★ 2,966repo stars module-shape The module-shape rule keeps public module APIs small while hiding complexity inside. Use it when designing modules or reviewing tests and dependencies. CX Codex +1 ★ 2,966repo stars parallel-worktrees parallel-worktrees — a skill for Claude Code that creates isolated git worktrees for parallel coding sessions. While tests or builds run in one window, start a new task in another without waiting or switching context. CX Codex +1 ★ 2,966repo stars compact-guard compact-guard is a Claude Code skill that records task state before context compaction and helps restore it afterward. Run it before /compact or when an auto-compaction warning appears. CX Codex +1 ★ 2,966repo stars handoff Generates a structured handoff document for passing work to another Claude session or your future self. Records status, decisions, learnings, and a resume point. CX Codex +1 ★ 2,966repo stars replay replay finds relevant past learnings and mistakes in a local SQLite database before starting a task. Surfaces project context to reduce repeated edits. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open