# Architecture Optimization

> Slow, tangled codebase → fast and cleanly bounded — a guided journey that orchestrates 8 AI agent skills, one decision at a time.

Published 2026-08-30 · Updated 2026-08-30 · Guided journey · Free and MIT-licensed
Canonical: https://skills.wondel.ai/skills/architecture-optimization/
Source: https://github.com/wondelai/skills/tree/main/architecture-optimization
Companion guide: https://skills.wondel.ai/guides/make-a-slow-app-measurably-faster/

**Install:** `npx skills add wondelai/skills/architecture-optimization --global`

## 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.

## The 8 phases

1. **Legacy Code** _(gate)_ — Is behavior pinned and performance measured, so every change is provable? → `docs/PERFORMANCE.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/working-with-legacy-code/)
2. **Clean Architecture** — Do dependencies still point inward, or has the boundary drifted as the code grew? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/clean-architecture/)
3. **Software Design** — Are modules deep, or has the structure itself become the complexity? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/software-design-philosophy/)
4. **Refactoring** — Can we reshape the hot paths in named, behavior-preserving steps? → `docs/TECH-DEBT.md + docs/TESTING.md` (https://skills.wondel.ai/skills/refactoring-patterns/)
5. **System Design** — What does the measured load say the bottleneck is, and what is the cheapest fix? → `docs/PERFORMANCE.md + docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/system-design/)
6. **Data-Intensive Apps** — Is the data layer the bottleneck — queries, indexes, isolation, derived data? → `docs/ARCHITECTURE.md + docs/PERFORMANCE.md` (https://skills.wondel.ai/skills/ddia-systems/)
7. **Release It!** — Does it stay fast and stable when a dependency is slow or down? → `docs/RELIABILITY.md` (https://skills.wondel.ai/skills/release-it/)
8. **Pragmatic Programmer** — What budgets and habits keep it fast and clean after we stop? → `docs/PERFORMANCE.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/pragmatic-programmer/)

## What it produces

- `docs/PERFORMANCE.md`
- `docs/TECH-DEBT.md`
- `docs/ARCHITECTURE.md`
- `docs/TESTING.md`
- `docs/RELIABILITY.md`
- `docs/ARCHITECTURE-OPTIMIZATION-PLAN.md`

## When 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.

## Example prompts

- Our API got slow as we grew — profile it and optimize the hot paths. using architecture-optimization skill _(Hot paths)_
- Run the architecture-optimization journey: baseline first, then boundaries and queries. using architecture-optimization skill _(Baseline first)_
- Resume the optimization journey and check the ledger before/afters. using architecture-optimization skill _(Resume journey)_

## Worked example — 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.
```

## 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.