Perf Check

Performance Investigation

Systematic approach to finding and fixing performance issues. Profile first, optimize second.

Steps

1. Define the problem:

• What's slow? (endpoint, page load, build, test suite, query)
• How slow is it? Get a baseline measurement
• What's the target? (e.g., "API response under 200ms")
• When did it start? (recent regression vs. always slow)

1. Profile before optimizing:

• Node.js: --prof flag, clinic.js, or 0x for flamegraphs
• Frontend: Chrome DevTools Performance tab, Lighthouse
• Database: EXPLAIN ANALYZE on slow queries
• General: time the operation with console.time() or equivalent
• Record the baseline numbers precisely

1. Identify the bottleneck:

• Where is time actually being spent? (CPU, I/O, network, database)
• Is it a single slow operation or death by a thousand cuts?
• Look for: N+1 queries, missing indexes, unnecessary re-renders, blocking I/O, large payloads

1. Prioritize fixes:

• Fix the biggest bottleneck first — often one fix solves 80% of the problem
• Estimate effort vs. impact for each potential fix
• Don't optimize things that aren't in the hot path

1. Implement the fix:

• Make ONE change at a time
• Common fixes: add database index, add caching, reduce payload, batch queries, lazy load, debounce
• Keep the code readable — clever optimizations that nobody can understand aren't worth it

1. Measure after:

• Run the same profile/benchmark as step 2
• Compare before/after numbers precisely
• Did it meet the target? If not, go back to step 3

1. Document the result:

• What was the bottleneck?
• What was the fix?
• Before/after numbers
• Any trade-offs made (memory vs. speed, complexity vs. performance)

Important

• Profile before optimizing. Guessing at bottlenecks wastes time on the wrong thing.
• Measure before AND after. "It feels faster" is not evidence. Numbers are evidence.
• One change at a time. Multiple simultaneous changes make it impossible to know what helped.
• Don't optimize prematurely. If it's fast enough, leave it alone.
• Readability > cleverness. A 10% speedup that makes code unreadable isn't worth it unless you're in a hot loop.

Source & license

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

• Author: ao92265
• Source: ao92265/claude-code-playbook
• License: MIT

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