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.
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.
One prompt runs it
npx skills add wondelai/skills/architecture-optimization --global This skill is compatible with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent, and other agentskills.io-compatible agents.
Example prompts for the Architecture Optimization journey
Our API got slow as we grew — profile it and optimize the hot paths. using architecture-optimization skill
Hot pathsRun the architecture-optimization journey: baseline first, then boundaries and queries. using architecture-optimization skill
Baseline firstResume the optimization journey and check the ledger before/afters. using architecture-optimization skill
Resume journeyWhen to use Architecture Optimization — and when not to
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.
Frequently asked questions
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.
Install Architecture Optimization
Free, open-source, and ready in 30 seconds.
npx skills add wondelai/skills/architecture-optimization --global MIT Licensed · Works with Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw, Hermes Agent & other agentskills.io agents · No account needed
Don’t guess your AI engineering level.
Measure it.
AI Developer Scorecard
How production-grade is your AI engineering?
Twenty-five questions across the practices that separate vibe-coding from production-grade engineering. Instant score, per-section breakdown, and a 30/60/90-day playbook.
Score 0–75 · 30/60/90-day playbook Score yourself For CTOs & foundersCTO Scorecard
Is your engineering team ready for AI at scale?
Twenty-five questions on how your org adopts AI — adoption, governance, automation, and ROI. See where you sit on the path from Reactive to Strategic Leader.
Score 0–75 · Reactive → Strategic Leader Score your orgWe build the skills you already use. Now we’ll build yours.
Fixed-price engagements, quoted after a 15-minute call. Shipped to production, or you don't pay the final milestone.