performance-tuning（性能调优）

Performance Tuning

Overview

Blind optimization is the root of wasted effort. Measure, pinpoint the bottleneck, fix that specific thing.

Core principle: No optimization without measurement. No measurement without a demonstrated performance problem.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO OPTIMIZATION WITHOUT A MEASUREMENT PROVING THE PROBLEM

If you have not profiled it, you are not qualified to optimize it. Intuitions about performance are reliably wrong.

When to Use

digraph perf_gate {
    problem [label="Is there a\nmeasurable\nperformance deficit?", shape=diamond];
    measure [label="MEASURE\nProfile and locate\nthe bottleneck", shape=box, style=filled, fillcolor="#ccffcc"];
    halt [label="HALT\nDo not optimize", shape=box, style=filled, fillcolor="#ffcccc"];
    found [label="Bottleneck\npinpointed?", shape=diamond];
    fix [label="FIX\nthat specific thing", shape=box, style=filled, fillcolor="#ccccff"];
    dig [label="Investigate further\nor accept current\nperformance", shape=box];

    problem -> measure [label="yes"];
    problem -> halt [label="no"];
    measure -> found;
    found -> fix [label="yes"];
    found -> dig [label="no"];
    fix -> measure [label="re-measure"];
}

Engage when:

• Users report perceptible slowness
• Telemetry shows regression (response time, page load, throughput)
• Performance budgets are breached (bundle size, Core Web Vitals)
• Database queries exceed 100ms for routine operations
• API responses exceed 500ms for typical requests

Do not engage when:

• "It might be slow someday" (measure when it actually is)
• "Best practice recommends optimizing X" (is X actually slow?)
• Current performance satisfies current requirements
• The feature does not yet work correctly (correctness first)

The Entry Protocol

BEFORE any optimization effort:

1. MEASURE: What is the current performance? (Numbers, not hunches)
2. TARGET: What performance level is required? (Specific threshold)
3. PINPOINT: Where is the bottleneck? (Profiler data, not speculation)
4. FIX: Address that specific bottleneck
5. VERIFY: Did the measurement improve? By how much?

Omit any step = premature optimization

The Methodology

Phase 1: Establish a Baseline

You must have numbers before changing anything.

Record the baseline. You need it to prove the optimization was effective.

Phase 2: Locate the Bottleneck

The bottleneck is almost never where you expect it.

Profile -> identify the function/query/resource consuming the most time
                                    |
                    That is your optimization target
                                    |
                    Everything else is a distraction

Check these locations in order (most common first):

1. Database queries -- N+1 patterns, absent indexes, full table scans
2. Network calls -- Sequential when parallelizable, no caching layer
3. Serialization -- Oversized payloads, unnecessary nested data
4. Computation -- Suboptimal algorithms, redundant processing
5. I/O operations -- File system access, disk reads, external API latency

Phase 3: Resolve the Bottleneck

Fix only what the profiler revealed. Change one variable at a time.

Database Tuning

-- BEFORE: Diagnose the problem
EXPLAIN ANALYZE SELECT * FROM transactions WHERE account_id = 789;

-- Look for: Seq Scan (missing index), high cost, slow execution
-- AFTER: Add index, re-run EXPLAIN ANALYZE, compare numbers

Frontend Tuning (Core Web Vitals)

Bundle weight reduction:

1. Audit: what occupies space in the bundle?
2. Remove unused dependencies
3. Code-split by route (lazy loading)
4. Ensure ESM imports for tree-shaking
5. Enable compression (gzip/brotli)

API Tuning

Algorithm Tuning

Only when the profiler points to computation as the bottleneck:

Phase 4: Confirm the Improvement

Re-run the identical measurement. Compare the numbers.

Baseline: API response 920ms
After optimization: API response 145ms
Improvement: 84% reduction
Required threshold: < 500ms -- ACHIEVED

If the improvement is not measurable, revert the change. An optimization that cannot be measured is not an optimization.

Anti-Patterns to Avoid

Cognitive Traps

Guardrails -- HALT and Measure

• Optimizing without profiler output on hand
• "While I am here, let me tune this..."
• Adding a cache without measuring what is slow
• Optimizing code that runs once (startup routines, one-time migrations)
• Sacrificing readability for unmeasured performance gains
• Solving scaling problems that do not yet exist
• Applying multiple optimizations simultaneously (isolate impact per change)

Every item on this list means: HALT. Measure first. Optimize only the measured bottleneck.

Integration

Complementary skills:

• godmode:system-design -- Architectural choices that influence performance characteristics
• godmode:completion-gate -- Validate optimization with measurements
• godmode:quality-enforcement -- Performance budgets as automated quality gates

The Bottom Line

Measure -> Pinpoint bottleneck -> Fix that one thing -> Confirm improvement

Everything else is speculation. Speculation about performance is always wrong.