performance

---
name: performance
description: Use for performance budgets, diagnosing slowness or high cost, optimizing latency/throughput/resources — spec NFRs, hot paths, pre-launch audit. Measure before optimizing.
---

# 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
1. **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.
2. **Establish a baseline.** Measure current behavior with representative data and load before changing anything. Without a baseline you cannot prove improvement or regression.
3. **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.
4. **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.
5. **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.
6. **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`.
7. **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.
8. **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`

More agent context in muxammadmamajonov/dot-claude

74 other files this repository gives its agents, the first 60 shown.