From improve-code-architecture
Use when code needs structural improvement via module boundaries, decoupling, layer isolation, or abstraction — long files mixing concerns, tight coupling, I/O tangled with business logic, duplicated shapes, hard-to-test units, or ripple-effect changes. Applies software design patterns to produce testable, readable, modular, maintainable, reusable code. Not for one-off scripts or cosmetic cleanup.
How this skill is triggered — by the user, by Claude, or both
Slash command
/improve-code-architecture:improve-code-architectureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Apply software design patterns to **decouple modules, isolate layers, and introduce clean abstractions**. The goal is not "more patterns" — it is **clear seams between things that change for different reasons**.
Apply software design patterns to decouple modules, isolate layers, and introduce clean abstractions. The goal is not "more patterns" — it is clear seams between things that change for different reasons.
Core principle: Every extraction must answer what concern does this boundary hide? If you cannot name it, do not extract.
Start with architecture-lens if you are implementing inside an existing plan. It is lighter and catches most drift. Escalate to this skill only when the problem ripples across 3+ files or needs a new seam that does not exist yet.
Symptoms that mean this skill applies:
process.env at import timeany types at internal boundaries| Quality | What it means | Typical fix |
|---|---|---|
| Testable | Unit can be exercised without real I/O | Dependency Injection, Port/Adapter |
| Readable | A stranger understands the flow in 60s | Facade, intention-revealing names |
| Modular | Pieces have clear seams and owners | Repository, layering, bounded contexts |
| Maintainable | Safe to change one concern at a time | Strategy, Decorator, single responsibility |
| Reusable | Same unit works in another context unchanged | Pure functions, explicit contracts |
Rule: Diagnose which 1–2 are actually broken. Fix those. Leave the rest alone.
Before reading any code in depth, ask 3–5 concrete questions. Do not proceed until answered:
Skipping this step is the most common failure mode — do not reason about patterns before you know the pain.
If the user explicitly waives ASK ("skip the questions, just do it"): acknowledge, then state the answers you are assuming for each of the five questions in one line each, and proceed. Silently skipping is not allowed; assumptions must be visible so the user can correct them.
Scale workflow depth to scope. Refactoring a 50-line helper does not need a six-section plan — one paragraph and one commit is fine. The ASK/DIAGNOSE/PLAN/CONFIRM/IMPLEMENT shape is mandatory; the weight of each step scales with the blast radius.
Read the target code. For each of the five qualities, rate: OK / Weak / Broken. Write one line per rating citing concrete evidence (line numbers or snippets).
Scale read strategy to scope. If the in-bounds list is >1 file or totals >~300 lines, dispatch a subagent to read and rate, and only pull its findings (the OK/Weak/Broken table + one-line evidence per quality) back into main context. Do not load full source into main context when a summary will do. For a single small file, read directly.
Name the 1–2 broken qualities. Those drive the plan. A skill scope that tries to fix all five is a rewrite, not a refactor.
Write a plan containing exactly these sections:
patterns-reference.md.Present the plan to the user. Wait for explicit approval. Do not begin implementing.
If the user asks for changes, update the plan and re-present. Do not start coding mid-discussion.
Rules:
superpowers:test-driven-development.| Excuse | Reality |
|---|---|
| "The pain is obvious, I can skip ASK" | Constraints and non-goals are never obvious from code. Ask. |
| "Interface now, implementation later" | Speculative interfaces rot before their second caller arrives. |
| "This pattern is a best practice" | Patterns are context-dependent solutions, not defaults. |
| "I'll refactor and add tests together" | Then you cannot tell which change broke behavior. Tests first. |
| "The plan is in my head" | Un-written plans skip the approval gate and drift during coding. |
| "Just one more extraction" | Extraction without a named hidden concern is churn. |
| "We'll need this boundary eventually" | Eventually ≠ now. Cost is paid today, benefit is speculative. |
| "User said skip questions, so no ASK" | User override is allowed — but you must state the answers you're assuming, in one line each, before proceeding. |
| "This file is small, the workflow is overkill" | Keep the five-step shape; shrink each step to match. One-paragraph plans count. |
| "I'll generalize into a framework while I'm here" | Scope creep. Fix the 1–2 broken qualities named in DIAGNOSE, nothing else. |
Detailed pattern catalog with when to use / when NOT to use / code shape:
→ See patterns-reference.md
Patterns covered: Dependency Injection, Strategy, Repository + Unit of Work, Ports & Adapters (Hexagonal), Facade, Decorator, Factory, Command, Observer / Domain Events, Adapter, Template Method.
| Concern to hide | Pattern |
|---|---|
| Concrete collaborator (DB, clock, HTTP) | Dependency Injection |
| Choice of algorithm at runtime | Strategy |
| Persistence / query details | Repository (+ Unit of Work for multi-write consistency) |
| Domain from all I/O | Ports & Adapters |
| Complex subsystem behind one verb | Facade |
| Cross-cutting behavior (logging, retry, auth) | Decorator |
| Construction complexity / wiring | Factory |
| Reifying an operation (undo, queue, audit) | Command |
| Reacting to a thing that happened | Observer / Domain Event |
| Integrating an incompatible interface | Adapter |
| Fixed workflow with swappable steps | Template Method |
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub zachcr-ws/improve-code-architecture --plugin improve-code-architecture