Performance Evidence

Core rule

Never optimize from intuition alone. Capture a repeatable baseline, profile the bottleneck, change one dominant cause, then measure again.

Contract

Define workload, hardware/runtime, dataset, warm/cold state, sample count, and metric before editing. Separate CPU, I/O, network, allocation, lock contention, startup, and external-service latency.

Use percentiles for latency when variance matters. Compare correctness alongside performance so a faster broken path cannot win. For token/cost optimization, include retries and cache hits/misses—not just one call’s nominal price.

After improvement, rerun the same benchmark and a representative real workload. Record both absolute values and percentage change.

Microbenchmarks prove only their scoped operation; do not generalize them to end-to-end performance without an end-to-end measurement.