muxammadmamajonov Performance: Budgets, Profiling, Optimization
When to use
- Setting performance/cost targets for a feature or the system (part of the spec's non-functional requirements).
- A page, query, endpoint, job, render loop, or model call is slow or expensive.
- Capacity, latency, throughput, memory, or cloud cost is trending the wrong way.
- Running the performance audit phase before production readiness.
Applies to all project types: web vitals, mobile frame time and battery, API latency/throughput, batch job runtime, game frame budget, query cost, and LLM/agent token cost + latency.
Workflow
- Set budgets first. Define measurable targets tied to user impact: e.g. p95 latency, throughput at target load, payload/bundle size, memory ceiling, frame budget (16.6ms @60fps), cost per request/1k operations. Record them in the spec's non-functional section.
- Establish a baseline. Measure current behavior with representative data and load before changing anything. Without a baseline you cannot prove improvement or regression.
- Profile to find the real bottleneck. Use a profiler/tracer/flame graph, query
EXPLAIN, network waterfall, or APM trace. Identify where time/CPU/memory/allocations/cost actually go. Do not optimize from intuition. - Fix the dominant cost first. Target the biggest contributor per Amdahl's law. Common wins: eliminate N+1 queries, add the right index, cache or memoize, batch/parallelize I/O, reduce payload/serialization, stream instead of buffer, defer/lazy-load, raise concurrency, pick a better algorithm/data structure.
- Re-measure against the baseline and budget. Confirm the change moved the metric and did not regress others (correctness, memory, cost). Keep changes small and individually measured.
- Add a guardrail. Add a perf test, benchmark, or budget check so the gain doesn't silently regress. Wire budget assertions (e.g. bundle size, query count, p95) into CI where feasible — see
.claude/skills/devops/SKILL.md. - Validate under load. For throughput-sensitive systems, run a load/soak test at and beyond target load; watch latency percentiles, error rate, saturation, and cost. Find the knee of the curve.
- Audit before launch. Confirm budgets are met at expected scale, scaling/back-pressure works, and cost is acceptable. Document the profile, the fix, and remaining headroom.
Standards
- Do measure before and after every change; optimize against data, never against a hunch.
- Do use percentiles (p95/p99), not averages — tail latency is what users feel.
- Do test with production-scale data and realistic load; small datasets hide N+1s and missing indexes.
- Do fix algorithmic complexity (O(n²) → O(n log n)) and bad queries before micro-tuning.
- Do cache deliberately with explicit invalidation and TTLs; cache correctness bugs are worse than slowness.
- Do treat cost as a budget too (cloud spend, egress, tokens) — fast but bankrupting is a failure.
- Do offload slow/expensive work to async jobs/queues and add back-pressure and timeouts.
- Do-not optimize prematurely or sacrifice correctness, readability, or security for speed that no budget required.
- Do-not add caching/concurrency without thinking through invalidation, races, and memory growth.
- Do-not rely on one run; account for warmup, GC, JIT, and noise — repeat measurements.
- Do-not ship perf changes without a regression guard.
Common mistakes to avoid
- Optimizing the wrong thing: tuning a function that's 2% of runtime while ignoring the 70% spent in a query.
- Testing performance on tiny datasets, so N+1 queries and missing indexes never surface until production.
- Reporting averages that hide a brutal p99; or a single benchmark run treated as truth.
- Caching without invalidation, producing stale-data bugs that are hard to trace.
- Adding threads/async and creating races, deadlocks, or unbounded resource growth.
- Premature micro-optimization that complicates code for gains no budget asked for.
- Ignoring cost: a "fast" design that 10× the cloud or token bill at scale.
Output format
A performance record: the budgets, the baseline numbers, the profiling evidence (flame graph / EXPLAIN / trace summary), the change made, and the after numbers vs budget, plus the guardrail added. For audits, a table of budget vs measured at target load with pass/fail and remaining headroom. Link from the spec's non-functional section (.claude/templates/product-spec.md).
Related checklists
.claude/checklists/performance.md.claude/checklists/production.md.claude/checklists/qa.md
Related agents
.claude/agents/quality/performance-engineer.md.claude/agents/engineering/backend-engineer.md.claude/agents/core/orchestrator.md