# Architecture Optimization

Guided journey from a working codebase grown slow and tangled to one measurably fast...

- Repository: https://github.com/wondelai/skills (2552 stars)
- Category: Design
- License: MIT
- Last updated: 2026-09-10
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add wondelai/skills --skill architecture-optimization -g -a claude-code -y`
Codex: `npx skills add wondelai/skills --skill architecture-optimization -g -a codex -y`
Cursor: `npx skills add wondelai/skills --skill architecture-optimization -g -a cursor -y`
Gemini CLI: `npx skills add wondelai/skills --skill architecture-optimization -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add wondelai/skills`

## Description

Guided journey from a working codebase grown slow and tangled to one measurably fast, cleanly bounded, and readable. Orchestrates eight skills phase by phase - working-with-legacy-code, clean-architecture, software-design-philosophy, refactoring-patterns, system-design, ddia-systems, release-it, pragmatic-programmer - every phase carries its method inline so it runs standalone, asking the user questions at every decision point and recording results in the project docs/ folder (PERFORMANCE.md, ARCHITECTURE.md, ARCHITECTURE-OPTIMIZATION-PLAN.md) so the journey resumes across sessions. Use when the user wants to make an app faster, untangle drifted boundaries, fix slow endpoints and queries, or says ''it works but it is slow and getting worse''. For an untested prototype, improve-code-quality; for an aged codebase you fear to touch, remove-technical-debt; for greenfield structure, design-code-architecture; for marketing-site page speed, improve-website. For one framework in isolation, invoke that skill directly.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Architecture Optimization

Optimize a working codebase on three axes at once, architecture, code quality, and performance, without breaking what works. This is an interactive, resumable journey of eight phases: the agent asks
before every decision and records the outcome in your project's `docs/` folder, so you can stop after
any phase and pick up later. It is for a system that ships and earns but has grown slow and tangled;
the structure phases make the code safe and cheap to change, the performance phases make it measurably
fast, and the closing phases keep it that way.

## Core Principle

**Measure before optimizing, pin before restructuring, the profiler and the safety net decide, not
intuition.** Premature optimization is the root of much evil not because optimization is bad, but
because unmeasured optimization targets the wrong 97% of the code; and a restructure without pinned
behavior is a gamble, not an improvement. This skill sequences the phases, asks the decision
questions, and records every choice in `docs/`. The constituent skills carry the method, invoke them
rather than improvising their frameworks.

## Journey Map

The rest: https://github.com/wondelai/skills/blob/HEAD/architecture-optimization/SKILL.md