Performance At Scale

The rule

Hot-path code meets your data at production scale, not at the handful of rows in your test fixture. A linear scan that's instant on ten items freezes the UI on a hundred thousand. The cost is invisible in the test and brutal in the field. Design the hot path for the largest realistic input before you write it, not after a user reports a freeze.

Fires when

Writing code that runs per item, per frame, or per event. Building a cache or a lookup. Iterating a collection that could grow large. Rebuilding a whole list when one entry changed.

How to apply

Before writing data-path code, ask "does this hold at the largest realistic input?"

Use O(1) lookups with an early exit — a map keyed by the thing you're asking about, so 99% of queries return immediately. Prefer incremental point updates (remove one, add one) over rebuilding the whole structure. Keep allocations and copies out of tight loops. Verbose logging in a hot loop is fine, but only after the early exit, never before it.

If the answer is "no, it won't scale", redesign before you write it, not after.

Worked example

A handler runs once per tile and scans a flat list of issues linearly to find the ones that match. With a dozen issues in the test, it's instant. In a real project the list holds four thousand issues, and every tile now costs a one-to-two second freeze. Keyed into a map by tile, each query early-exits in O(1) and the freeze is gone. The scan looked fine because the test never had enough data to make it hurt.

Red flags

| Thought | Reality | |---|---| | "It's fast enough" | Fast on the fixture, frozen at scale. | | "I'll rebuild the whole list, it's simpler" | Simpler to write, O(N) to run every time. | | "Just loop and find it" | A linear scan on a hot path is a freeze waiting for data. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Fergius-Engineering
• Source: Fergius-Engineering/instincts
• License: MIT

Install and usage instructions live in the source repository linked above.