Performance Optimization Prompt

在拿到真实 profile 之前禁止改任何代码：先定目标与分位数，再测量、找真因，然后按固定顺序修复——缓存排在第六位。

第零条规则：在 profiler 的真实输出指明时间去向之前，不许改代码。随后依次：说明具体操作、当前的真实数字、目标值及其理由、以及关心哪个分位数；测量并建立可重跑的基线；区分「本身慢」与「被调用次数远超应有」；再按顺序修复——少做、只做一次、延后做、换算法、加缓存、并行化、微优化。最后要求在多个输入规模上验证效果，并诚实判断这次改动是否值得。另附调用次数、前端、数据库三个变体。

# Performance Optimization

**Use when:** something is slow, or you want to know whether it is.
**Pairs with:** [debugging.md](debugging.md), [test_engineering.md](test_engineering.md)

Agents optimise by pattern. They see a loop and add memoisation. They see a query and add a cache. Sometimes it helps. Usually it adds complexity to code that was never the bottleneck. This prompt bans changes without measurement.

---

## The prompt

```text
Performance work. Measurement first. No change without a number.

RULE ZERO
You may not change any code until you can show me, with real output,
where the time actually goes. Not where you think it goes. Intuition
about performance is wrong often enough to be useless.

STEP 1: DEFINE THE TARGET
- What exactly is slow? The specific operation, from what event to what
  event.
- How slow is it now? A real number, measured.
- How fast does it need to be, and why that number? "Faster" is not a
  target. "Under 100ms so the interaction feels instant" is.
- Which percentile matters? p50 hides the problem. p95 and p99 are where
  users live.
- What input size does this happen at in production? Measure at that
  size, not at the size in the test fixture.

STEP 2: MEASURE
- Profile it. Show the real output.
- Where does the time go? Rank by total time, and separate self time from
  time spent in children.
- Is it CPU, memory allocation, input and output, network, lock
  contention, or waiting on something else? These have different fixes
  and confusing them wastes days.
- Establish a baseline you can rerun. Give me the exact command.

STEP 3: FIND THE REAL CAUSE
The top line of a profile is a symptom. Ask why it is expensive.
- Is it slow, or is it called far more often than it should be? Count the
  calls. This is the answer more often than people expect.
- Is it doing work that could be done once instead of every time?
- Is it doing work that does not need to be done at all?
- Is the algorithm wrong for this size, or is the constant factor bad?
  Those need opposite fixes.
- Is it a call inside a loop that should be one batched call?

STEP 4: FIX IN THIS ORDER
Try them in order. Stop as soon as you hit the target.
1. Do less. Remove the work. Fastest code is code that does not run.
2. Do it once. Hoist, batch, precompute.
3. Do it later, or not at all until asked. Lazy, on demand, paginated.
4. Better algorithm or data structure.
5. Cache. Only now, because a cache is a correctness problem you are
   choosing to take on. Say what invalidates it before you add it.
6. Parallelise.
7. Micro optimise. Almost never the answer.

STEP 5: PROVE IT
- Measure again with the same command. Show before and after side by side.
- Report the real change: from X to Y, a Z percent improvement, at the
  percentile that matters.
- Run at more than one input size. A fix that helps at 100 items and
  hurts at 100000 is a bug.
- Run the tests. Show they pass. Fast and wrong is worthless.
- State the cost of the fix: more memory, more complexity, more code, a
  new failure mode, a cache that can go stale.

STEP 6: DECIDE IF IT WAS WORTH IT
Honestly. If the fix made the code meaningfully harder to understand for
a 3 percent gain nobody notices, say so and recommend reverting.

BANNED
- Optimising anything the profile did not point to.
- "This should be faster."
- Adding a cache before understanding what is slow.
- Reporting a percentage without the absolute numbers. 50 percent faster
  on 2ms is nothing.
- Benchmarking on a warm cache and calling it representative.
- Changing several things at once, so you cannot tell what helped.
```

---

## The call count question

Before profiling anything, ask this:

```text
How many times is this called for one user action? Count it, do not
estimate. If the answer is surprising, that is the bug, and no amount of
making the function faster will fix it.
```

The N+1 query, the render loop that runs on every keystroke, the function called once per array item that should be called once. These are the most common real causes and a profiler shows them as "this function is slow" rather than "this function is called 4000 times".

---

## For frontend

```text
Measure what the user feels, not what the machine does.
- Time to first meaningful paint, time to interactive, input latency,
  frame rate during scroll and animation.
- Where does the main thread block for more than 50ms?
- Bundle size, and what is in it that should not be.
- Layout thrash: reads and writes to layout interleaved in a loop.
- Images: correct size, correct format, correctly lazy.
Report in milliseconds the user experiences, not in operations per second.
```

---

## For database work

```text
- Show the query plan. Not a guess about the plan. The actual plan.
- Is it a full scan? On how many rows?
- Is the index used? If not, why not: wrong column order, a function on
  the column, type mismatch, low selectivity.
- Rows examined versus rows returned. A large gap is the problem.
- Is this one query or is it inside a loop?
- Would fetching less data solve it more simply than a new index?
```

---

## Why it works

Rule zero carries the prompt. Everything downstream depends on refusing to let the model change code before it has a measurement.

The ordered fix list matters because it puts caching sixth. Left alone, agents reach for a cache first, and a cache turns a performance problem into a correctness problem that shows up weeks later as stale data.