improve-code-architecture

Improve Code Architecture

Overview

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.

When to Use

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:

• One file / function does HTTP + DB + external API + business rules
• Changing one feature forces edits in many files (shotgun surgery)
• Tests require the real DB, real HTTP, or mocked SDKs
• The same shape repeats in slightly different forms (3+ times)
• You cannot describe a module's responsibility in one sentence
• Module-level singletons wired from process.env at import time
• any types at internal boundaries

When NOT to Use

• One-off scripts or throwaway tooling
• Cosmetic cleanup (renaming, formatting) — that's not architecture
• There are no tests AND no budget to add them — refactoring without tests is rewriting
• You cannot name a concrete pain point beyond "this feels messy"

The Five Qualities (outcomes, not a checklist)

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.

Workflow

1. ASK (mandatory — do not skip)

Before reading any code in depth, ask 3–5 concrete questions. Do not proceed until answered:

• Pain: What specifically breaks today? ("slow tests", "Stripe swap is scary", "on-call pages when tax API is down")
• Scope: Name the exact files/symbols in bounds (paths). Name what is explicitly out. If the list exceeds ~8 files, stop and decompose — this skill runs per-bounded-context, not per-repo.
• Tests: What coverage exists? Which paths are exercised? Can we add a characterization test first?
• Constraints: Public API that cannot change? Performance budget? Deployment model (single process, serverless, etc.)?
• Non-goals: What would be a bad outcome even if "cleaner"? (e.g., "don't introduce an ORM", "no new services")

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.

2. DIAGNOSE

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.

3. PLAN

Write a plan containing exactly these sections:

1. Current structure — ASCII sketch of what is where
2. Target structure — ASCII sketch of what it will become (files, modules, responsibilities)
3. Patterns applied — for each pattern, one line: "Pattern X hides concern Y so Z can change independently." If you cannot fill that template, do not use the pattern. See patterns-reference.md.
4. Migration sequence — ordered steps; each step is independently shippable and behavior-preserving
5. Trade-offs accepted — what gets worse (file count, indirection, build time) in exchange for what
6. Verification — how you will prove behavior is preserved (characterization tests, contract tests, canary)

4. CONFIRM

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.

5. IMPLEMENT

Rules:

• Tests first. If characterization tests do not exist, write them before moving code. See superpowers:test-driven-development.
• One concern per commit. "Extract PaymentGateway interface" is one commit. "Extract payment + add Strategy for shipping" is two commits.
• Strangler, not big bang. Keep the old path working; route new calls through the new structure; delete old only when new is proven.
• Behavior preservation over purity. If the purest design breaks an edge case, the edge case wins. Note the compromise in a comment.
• Stop and reconfirm if the plan no longer matches reality halfway through.

Red Flags — STOP and Reconsider

• "Let me add an interface for future flexibility" with one implementation → YAGNI. Wait for the second caller.
• Strategy pattern with one strategy → delete the indirection.
• Refactoring without a failing test or concrete user pain → you are reshuffling, not improving.
• Pattern count going up, readability going down → revert the last step.
• "I'll generalize this" on the second occurrence → wait for the third (rule of three).
• Skipping ASK because "the code speaks for itself" → the code does not know the constraints.
• Applying a pattern by name without filling the "hides concern Y" template.
• Fixing all five qualities in one PR.

Rationalization Table

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.

Design Pattern Reference

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.

Quick Reference — Boundary → Pattern

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