Architecture Optimization
Slow, tangled codebase → fast and cleanly bounded
Takes a working codebase that has grown slow and tangled to one that is measurably fast, cleanly bounded, and readable — without breaking what already earns. It orchestrates eight skills phase by phase, asking you the decision questions at every step and recording every result in your project’s docs/ folder so the journey resumes across sessions.
npx skills add wondelai/skills/architecture-optimization --global - 01
Is behavior pinned and performance measured, so every change is provable? gate
Legacy Code → docs/PERFORMANCE.md + docs/TECH-DEBT.md - 02
Do dependencies still point inward, or has the boundary drifted as the code grew?
Clean Architecture → docs/ARCHITECTURE.md - 03
Are modules deep, or has the structure itself become the complexity?
Software Design → docs/TECH-DEBT.md - 04
Can we reshape the hot paths in named, behavior-preserving steps?
Refactoring → docs/TECH-DEBT.md + docs/TESTING.md - 05
What does the measured load say the bottleneck is, and what is the cheapest fix?
System Design → docs/PERFORMANCE.md + docs/ARCHITECTURE.md - 06
Is the data layer the bottleneck — queries, indexes, isolation, derived data?
Data-Intensive Apps → docs/ARCHITECTURE.md + docs/PERFORMANCE.md - 07
Does it stay fast and stable when a dependency is slow or down?
Release It! → docs/RELIABILITY.md - 08
What budgets and habits keep it fast and clean after we stop?
Pragmatic Programmer → docs/PERFORMANCE.md + docs/TECH-DEBT.md
Each phase asks the question, then writes the answer before the next one starts.
The long read behind the phases: Make a Slow App Measurably Faster
02 What it is
What is the Architecture Optimization journey?
It ships, it earns, and it has gotten slow. Eight phases pin behavior and measure a baseline first, then work the drifted boundaries, the deep-module complexity, the hot paths, the measured bottleneck and the query layer — every optimization proving itself with before/after numbers in a ledger, and anything that misses its baseline reverted rather than kept.
03 In practice
Make a Working App Measurably Faster
It shipped, it earns, and it has gotten slow — but nobody knows which part is actually slow.
Our app has gotten slow: p95 on the main endpoints keeps climbing and the database bill with it. Run the architecture-optimization journey — baseline and pin behavior first, then boundaries, hot-path refactors, the measured bottleneck, and the query layer. Keep a before/after ledger in docs/PERFORMANCE.md and revert anything that does not beat its baseline.
Use architecture-optimization skill.
Written to your repo
- docs/PERFORMANCE.md
- docs/TECH-DEBT.md
- docs/ARCHITECTURE.md
- docs/TESTING.md
- docs/RELIABILITY.md
- docs/ARCHITECTURE-OPTIMIZATION-PLAN.md journey tracker
Stop anytime. The tracker records which phases are done and which decision is next, so a new session opens at the unanswered question.
04 Prompts
Say it like this.
Name the journey at the end of a prompt and it takes over from phase one. Say it again in a later session and it resumes at the unanswered question.
Our API got slow as we grew — profile it and optimize the hot paths. using architecture-optimization skill
Run the architecture-optimization journey: baseline first, then boundaries and queries. using architecture-optimization skill
Resume the optimization journey and check the ledger before/afters. using architecture-optimization skill
05 Fit
One prompt runs it.
Every phase asks before it acts, and every decision lands in your project's docs/ folder as a living document.
Reach for it when
Make slow endpoints and queries measurably faster, guided by a profile
Untangle boundaries that drifted as the codebase grew
Fix N+1 queries, missing indexes, and unbounded result sets by evidence
Keep latency stable when a dependency is slow or down
Turn performance budgets into CI gates so the gains hold
Reach for something else when
The prototype was built fast and has no tests at all. Improve Code Quality starts from there.
The codebase is aged and team-owned and nobody dares touch it. Remove Technical Debt paces that differently.
Nothing is built yet and the question is structure. Design Code Architecture decides boundaries first.
The slow thing is a marketing site’s page load. Improve a Website covers Core Web Vitals.
07 Questions
Before you install.
How do I install the Architecture Optimization journey?
Run npx skills add wondelai/skills/architecture-optimization --global. It takes about 30 seconds and needs no account. The Architecture Optimization skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.
Which skills does the Architecture Optimization journey run, and what does it produce?
It orchestrates 8 skills across 8 phases — Legacy Code, Clean Architecture, Software Design, Refactoring, System Design, Data-Intensive Apps, Release It!, Pragmatic Programmer — asking you one decision question per phase. Each answer is written to your project's docs/ folder (docs/PERFORMANCE.md, docs/TECH-DEBT.md, docs/ARCHITECTURE.md, docs/TESTING.md, docs/RELIABILITY.md, docs/ARCHITECTURE-OPTIMIZATION-PLAN.md), so the journey survives across sessions and you keep the reasoning, not just the output.
How is this different from Remove Technical Debt?
Debt removal is aimed at fear: the codebase is aged and team-owned, changes are risky, and the goal is making it safe to touch again while the team keeps shipping. This journey is aimed at speed with structure as the means: it assumes the code broadly works and asks the profiler which 3% actually costs you, then fixes boundaries and queries because that is where the latency lives. If your complaint is "it is slow", start here; if it is "we are afraid to change it", start there.
What does the measure-first gate refuse to let me do?
Optimize anything without a baseline, and restructure anything without pinned behavior. Phase one produces docs/PERFORMANCE.md with real numbers — p95s, slow queries, a profile — and a safety-net map of what is under test. Every later change cites the baseline it targets and lands in the Optimization Ledger with before and after. A change that does not move its number gets reverted, not kept, which is the rule that stops a month of plausible-looking work from adding up to nothing.
Why do resilience and habits come after the performance work?
Because timeouts, circuit breakers and CI budgets are about holding the gains, not producing them. Phases five and six find and fix the bottleneck; phase seven makes latency stable when a dependency degrades instead of collapsing; phase eight turns the numbers you earned into budgets that fail the build when they regress. Those last two are judged by their own done-when conditions rather than by a latency delta — they are not expected to make anything faster.
Can I run only the performance phases and skip the structural ones?
You can defer them, and the journey will say what you are trading. Boundaries and module depth are not decoration here: an N+1 query is usually a boundary problem, and a hot path nobody can read is a hot path nobody can safely optimize. Skipping phases two through four typically means the phase-five and phase-six fixes land as local patches that the next feature undoes. If time is short, the honest order is to defer rather than skip, and record the reason in the tracker.
Eight skills, one deliberate order.
Run the whole journey with one prompt.
npx skills add wondelai/skills/architecture-optimization --global MIT licensed · Claude, Claude Code, Codex, Cursor, OpenClaw, Hermes · No account