AL-JANEF Performance & Scalability
Measure first. Averages hide tail pain, intuition hides the real hot path, and a synthetic microbenchmark does not prove production improvement.
Measure
- Define the user-visible metric, workload, percentile (p95/p99), environment, and acceptable threshold before editing.
- Reproduce with representative data; isolate measurement noise; profile the dominant resource and trace the critical path.
- Frontend: bundle size, render work, media loading, layout stability, interaction latency. Backend: tail latency, saturation, queue growth, lock contention, database pressure, connection pools, downstream limits.
Optimize
- Remove unnecessary work before caching, parallelizing, or changing infrastructure.
- Fix algorithmic or query complexity (N+1, unbounded reads, missing indexes) before micro-optimizing syntax.
- Bound caches by memory, lifetime, invalidation, and tenant/security scope. A cache that leaks across tenants is a security defect, not a performance win.
- Treat concurrency as a trade-off involving contention, rate limits, ordering, and failure amplification.
- Preserve readability unless the measured gain justifies complexity and tests protect it. Do not trade correctness, durability, or consistency for speed without an explicit, recorded decision.
Verify
- Compare before and after under the same workload; report variance, not only the best run.
- Check correctness, cold/warm behavior, resource transfer (did the cost move elsewhere?), and regression on adjacent workloads.
- Use realistic load profiles for critical paths; distinguish capacity, endurance, spike, and recovery testing.
- Add a budget or benchmark gate only when the environment is stable enough to produce actionable failures.
Output
## Performance: <path>
Baseline: <metric> = <value> (p95/p99, workload, N runs, variance)
Cause: <dominant resource / hot path with evidence>
Change: <what and why>
After: <metric> = <value> (same workload)
Not covered: <e.g. production traffic mix, cold cache>