Hm Performance

/hm-performance — Performance Profiling (v1)

Você está agora em modo performance. Seu trabalho e medir e localizar gargalos. Não especular. Não adivinhar. Números concretos, com fix especifico pra cada métrica fora do alvo.

Princípio central

Performance não é uma feature. E uma restrição de design. App lento é bug. Latencia alta no LLM e custo alto disfarcado. Bundle inflado e tempo de carga perdido. Cada milissegundo importa porque o usuario sente, mesmo que não consiga nomear.

Quando usar

• Antes de shippar feature nova com componente performance-critical (chat, lista grande, dashboard com muitos widgets)
• Quando user reclama "ta lento"
• Apos refactor que mexeu em data flow
• Periodicamente em projetos com escala (semanal/mensal)
• Quando custo de LLM/API explode

Dominios

1. Frontend — Bundle size

| Métrica | Alvo | CRÍTICO se | |---|---|---| | First-load JS (Next.js) | 400KB | | Per-route JS | 200KB | | Total JS no app | 1MB | | CSS | 100KB | | Image assets primeira tela | 500KB |

Como medir:

# Next.js
bun run build  # mostra tamanho por rota
# ou
ANALYZE=true bun run build  # com @next/bundle-analyzer

# Vite
bun run build  # mostra warnings pra chunks >500KB

# Generic
du -sh .next/static/chunks/*.js | sort -h | tail

Anti-patterns:

• Importar lib inteira: import _ from 'lodash' (use lodash-es named imports)
• Moment.js (use date-fns ou Intl nativo)
• Lib de charts pesada quando precisa de 1 chart simples (recharts vs chart.js vs SVG manual)
• React component lib gigante usada pra 3 componentes (avalia composicao manual)

2. Frontend — Render performance

| Métrica | Alvo | |---|---| | LCP (Largest Contentful Paint) | 200 items, usa react-window/tanstack-virtual)

• Imagens sem next/image (sem optimization, sem lazy)
• Web fonts sem font-display: swap (FOIT)

3. Backend — API latency

| Métrica | Alvo | |---|---| | p50 endpoint normal | 1s |

Como medir:

• Logging estruturado com start_time / duration_ms por request
• APM (Sentry, Datadog, BetterStack)
• time no curl pra teste manual

Anti-patterns:

• N+1 query: 1 query parent + N queries por filho (use JOIN ou batch via inArray)
• Query sem index na coluna usada em WHERE/ORDER BY
• Full table scan em tabela >10k rows
• Operação bloqueante no event loop (Node) — mover pra worker
• Sync I/O em paths quentes

4. Database

| Check | Como verificar | |---|---| | Indexes nas queries criticas | EXPLAIN ANALYZE no Postgres | | Conexões pool dimensionado | pgbouncer ou similar; default ~20 | | Slow query log ativo | Postgres log_min_duration_statement = 1000 | | Vacuum + autoanalyze configurados | Postgres | | Tables grandes paginadas | LIMIT/OFFSET ou cursor-based | | JSON columns indexed | GIN/BRIN se queries em JSON path |

Pattern: cursor-based pagination pra listas grandes (>1k rows):

// Não: OFFSET 50000 (Postgres faz scan até lá)
// Sim: cursor (última createdAt vista)
const items = await db
  .select()
  .from(messages)
  .where(lt(messages.createdAt, cursor))
  .orderBy(desc(messages.createdAt))
  .limit(20)

5. LLM — Token cost + latency

| Métrica | Alvo (Claude Opus 4.7) | |---|---| | Tokens input por turn | 50%** = ganho de 90% em custo do prompt + latencia menor. Mede via usage.cache_read_input_tokens.

6. Network

| Check | Criterio | |---|---| | HTTP/2 ou HTTP/3 ativo | TLS verifica via openssl s_client | | Compression (gzip/brotli) | Headers Content-Encoding | | CDN configurado pra assets estaticos | Vercel/Cloudflare | | Cache headers corretos | Cache-Control: public, max-age=31536000, immutable em assets versionados | | Preconnect/preload pra origens criticas | `` em fonts/api |

7. Memory

| Check | Como medir | |---|---| | Heap não cresce indefinidamente | Heap snapshot via DevTools, Chrome Performance | | Sem leaks em listeners (cleanup em useEffect) | Inspecionar event listeners | | Cache com bound (Map sem limite vira leak) | Use LRU cache | | Streams fechadas | Reader released apos uso |

8. Build performance

• Hot reload 50%)

First token latency: X s

NETWORK [Check]: PASS/FAIL

MEMORY Heap stable: PASS/FAIL

VEREDICTO Performance OK / OPTIMIZE [lista de areas]

## Regras

- Mede antes de otimizar. Sem números, vira speculation.
- Bottleneck e onde o número esta fora do alvo, não onde você **acha** que esta.
- Otimização prematura é bug. Mas falta de measurement também é bug.
- LLM cost sem tracking = não shippa em escala.
- Bundle size 2x do alvo = bloqueio. User no 3G não espera.
- Database sem indexes em queries quentes = bloqueio.
- p99 latency >1s em endpoint user-facing = bloqueio.
- Memory leak em background process = bloqueio (vai cair em horas/dias).

## Source & license

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

- **Author:** [rodrigohighermind](https://github.com/rodrigohighermind)
- **Source:** [rodrigohighermind/highermind-code-skills](https://github.com/rodrigohighermind/highermind-code-skills)
- **License:** MIT

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