architecture-optimization
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, pra…
Install / Use
npx skills add wondelai/skills --skill architecture-optimizationInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of architecture-optimization
architecture-optimization scores 87/100 on our quality scale, 2154th of 4,698 Development & Engineering skills we index (top 46%).
Its SKILL.md is 29 KB long, well organised into 17 sections and no code examples: a thorough specification that gives an agent plenty to work with.
With 2,248 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so architecture-optimization is actively maintained.
- Our last check on 2026-11-02 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-30. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
architecture-optimization compared with similar skills
All 4 of these similar skills score higher than architecture-optimization; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| architecture-optimization (this skill)by wondelai | 87 | 2.2k | 2mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install architecture-optimization?
- Run
npx skills add wondelai/skills --skill architecture-optimization. The install tabs above show the steps for each supported agent. - Which AI agents does architecture-optimization work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is architecture-optimization safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is architecture-optimization still maintained?
- The repository was last updated about 2 months ago, so architecture-optimization is actively maintained.
Skill content
View source on GitHubname: architecture-optimization 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.' license: MIT metadata: author: wondelai version: "1.0.0"
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
| Phase | Skill | Question it answers | Artifact | |---|---|---|---| | 1 | working-with-legacy-code | Is behavior pinned and performance measured, so every change is provable? | Creates docs/PERFORMANCE.md + docs/TECH-DEBT.md; extends docs/TESTING.md — GATE | | 2 | clean-architecture | Do dependencies still point inward, or has the boundary drifted as the code grew? | Extends docs/ARCHITECTURE.md | | 3 | software-design-philosophy | Are modules deep, or has the structure itself become the complexity? | Extends docs/TECH-DEBT.md | | 4 | refactoring-patterns | Can we reshape the hot paths in named, behavior-preserving steps? | Extends docs/TECH-DEBT.md + docs/TESTING.md | | 5 | system-design | What does the measured load say the bottleneck is, and what is the cheapest fix? | Extends docs/PERFORMANCE.md + docs/ARCHITECTURE.md | | 6 | ddia-systems | Is the data layer the bottleneck — queries, indexes, isolation, derived data? | Extends docs/ARCHITECTURE.md + docs/PERFORMANCE.md | | 7 | release-it | Does it stay fast and stable when a dependency is slow or down? | Creates-or-extends docs/RELIABILITY.md | | 8 | pragmatic-programmer | What budgets and habits keep it fast and clean after we stop? | Extends docs/PERFORMANCE.md + docs/TECH-DEBT.md + docs/TESTING.md |
Operating Rules
- Resume first. Before anything else, read
docs/ARCHITECTURE-OPTIMIZATION-PLAN.mdand every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. - Intake on first run only. No tracker: run the Intake below, then create
docs/ARCHITECTURE-OPTIMIZATION-PLAN.mdwith every phase statusedpending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason. Done when the tracker exists and the user has confirmed the phase plan. - Phase entry. Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase
in-progresson proceed. Done when the user chose. - Skill invocation and fallback. Load the phase's skill and use it: each phase's Invoke line names the skill by slug — use that skill to run the phase. If it is not available, offer:
npx skills add wondelai/skills/<slug> --global. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. - In-phase decisions. Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect.
- Phase exit. Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows
done. - Artifact discipline. Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in
docs/. Every recommendation lands as a checkbox or a table row with owner and priority. See references/artifact-templates.md when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. - Never optimize unmeasured, never restructure unpinned. Every change made to reduce a measured baseline cites that baseline and lands in the PERFORMANCE.md Optimization Ledger with before/after — one that doesn't move its number gets reverted, not kept. (Resilience and gating work — timeouts, breakers, bulkheads, pagination, CI gates — is judged by the Done-when of its own phase, not by a latency delta.) Structural changes touch only code pinned in the Safety Net Map, preserve behavior, and land in structure-only commits separate from behavior and optimization commits.
Intake
Ask these before creating the tracker:
- What does the system do, and what does "too slow" cost — lost users, SLA breaches, infra bills? (Frames which metric matters and how much effort the journey is worth.)
- What is the evidence so far — APM traces, slow-query logs, p95 latencies, a cloud bill, or just complaints? (Feeds the Phase 1 baseline; complaints alone mean instrumentation comes first.)
- Which flows or endpoints hurt most, and which modules implement them? (Picks the hot paths every phase works on.)
- Do automated tests exist and run green? (Scopes the Phase 1 safety net — unpinned hot paths get pinned before anything touches them.)
- What is the stack — language, framework, ORM, database, cache — and where does it run? (Gates Phases 5-6.)
- What are the real load numbers — QPS average and peak, data volumes, growth rate? (Gates Phase 5 — sizing by numbers, not fear.)
- How much of the journey do you want now? (Phases 1-4 make it safe and clean to change; 5-6 make it fast; 7-8 keep it that way.)
Skip heuristics: compress Phases 2-3 to an audit-only pass when the structure is sound and the pain is purely performance — record what the audit found either way and status the phase done with an "audit only, no changes" note; skip Phase 7 only when a prior journey's RELIABILITY.md Integration-Point Audit is verifiably current (check the file, don't assume). Never skip Phase 1 — an optimization without a baseline is a guess, and a restructure without a net is a gamble.
Then create docs/ARCHITECTURE-OPTIMIZATION-PLAN.md from the template and confirm the plan. Done when the tracker exists with every phase statused and the user has confirmed the plan.
Phases
Phases run in the listed order — each assumes the previous phase's artifact exists. Structure before speed is deliberate: Phases 2-4 make the hot paths safe and cheap to change, which is what makes the Phase 5-6 optimizations small diffs instead of surgery. Any phase can be entered, skipped, or deferred per the Operating Rules, but Phase 1 gates them all — as two independent nets: pinned behavior unlocks Phases 2-4, and a recorded baseline unlocks Phases 5-6, so structure work need not wait on a profile that takes weeks to gather. Phases 5 and 6 may be swapped when the Phase 1 profile shows the database dominating: fixing an N+1 or a missing index before adding a cache is the skill's own cheapest-first law. When running any phase from its Brief (constituent skill not installed), read references/methods.md first — it carries each phase's full method, checklists, formulas, and heuristics; the Brief is only the summary.
Phase 1 — Pin it and measure it (working-with-legacy-code) — GATE
Purpose: Make every later change provable twice over — behavior pinned by tests, performance pinned by numbers. No phase touches unpinned code or optimizes an unmeasured path.
Brief (fallback): Two nets. Behavior: code without tests is legacy code — cover and modify, never edit and pray. Find the change points on the hot paths, break inline dependencies at the least-invasive seam (Parameterize Constructor with a production default; Extract and Override for one buried call), and write characterization tests that photograph actual behavior — assert something wrong, read the failure, pin the real value. Performance: profile before touching anything — the bottleneck is rarely where intuition points. Record p50/p95/p99 latency, throughput, and resource use per hot flow under realistic data volumes (dev-database timings lie), and work the USE method (Gregg) per resource: Utilization, Saturation, Errors for CPU, memory, disk, network, and connection pools. Set the budget each metric must meet, so "done" is a number, not a feeling.
Invoke: Use the working-with-legacy-code skill with the hot-path modules from intake. Ask for the seams and the smallest characterization-test set that pins current behavior of each flow to be optimized; then capture profiler or APM baselines for those flows.
Decide with the user: (1) Confirm the hot paths in scope — measured pain, not suspicion. (2) The budget per metric (e.g. checkout p95 < 500ms) and the tool of record (profiler, APM, load test) so before/after numbers stay comparable. (3) Bugs found while characterizing: pin the current behavior and ledger them, never silently fix — callers may depend on the quirk.
Artifact: Extend docs/TESTING.md ## Safety Net Map and ## Characterization Backlog; create docs/PERFORMANCE.md with ## Baselines & Budgets, ## Load Reality, ## Profile Findings, and ## Optimization Ledger; create-or-extend docs/TECH-DEBT.md ## Debt Ledger and ## Sprout / Wrap Register for bugs pinned as-is and untested hosts. Update the tracker.
Done when: every in-scope flow has pinned behavior (suite green) — which unlocks Phases 2-4 — and a recorded baseline with a budget, which unlocks Phases 5-6. Record the two separately; a profile still being gathered parks at awaiting-evidence with a Next Actions row rather than blocking the structure phases.
Phase 2 — Re-draw the drifted boundaries (clean-architecture)
Purpose: Restore the Dependency Rule the codebase grew away from — mixed concerns are why changes feel risky and why the slow parts can't be optimized in isolation.
Brief (fallback): Source dependencies point inward: Frameworks → Interface Adapters → Use Cases → Entities; nothing inner names anything outer. In a grown codebase the drift is concrete: business logic importing the ORM, controllers comput
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
