By name: hm-performance description: Profiling com metas concretas e fix por gargalo. Use antes de shippar feature performance-critical (chat, lista grande, dashboard), quando user reclama "tá lento", após refactor em data flow, periodicamente em projetos com escala, quando custo de LLM/API explode. Cobre 8 domínios — bundle size, Web Vitals (LCP/INP/CLS), API latency (p50/p95/p99), database queries, LLM tokens+cost, network, memory, build performance. Numbers concretos, não especulação.
/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) | <200KB gzipped | >400KB |
| Per-route JS | <100KB gzipped | >200KB |
| Total JS no app | <500KB gzipped | >1MB |
| CSS | <50KB gzipped | >100KB |
| Image assets primeira tela | <200KB total | >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'(uselodash-esnamed 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) | <2.5s |
| FID/INP (Interaction to Next Paint) | <200ms |
| CLS (Cumulative Layout Shift) | <0.1 |
| TTFB (Time to First Byte) | <600ms |
| Re-renders desnecessarios | Minimizado via memo/useMemo |
Como medir:
- DevTools → Lighthouse (audit local)
- web-vitals package + analytics
- React DevTools Profiler pra re-renders
Anti-patterns:
- Inline objects/arrays como props (criam novo ref a cada render → quebra memo)
- useEffect com dependências erradas (re-roda demais OU stale closure)
- Lista grande sem virtualizacao (>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 | <100ms |
| p95 endpoint normal | <300ms |
| p99 endpoint normal | <800ms |
| Endpoint com LLM streaming | First token <2s, total proporcional |
| Endpoint background (analytics, etc) | Aceitável >1s |
Como medir:
- Logging estruturado com
start_time/duration_mspor request - APM (Sentry, Datadog, BetterStack)
timeno 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 | <3000 (descontado system prompt) |
| Tokens output por turn | 200-2000 (variavel) |
| Cost por turn | <$0.05 chat normal, <$0.30 geração longa |
| First token latency | <2s |
| Tokens/sec output | 30-80 (Anthropic streaming) |
| Cost por usuario/mês | Estimar e definir alerta |
Pattern: prompt caching (Anthropic):
// System prompt + facts grandes que não mudam → cache
const response = await anthropic.messages.create({
model: 'claude-opus-4-7',
max_tokens: 1024,
system: [
{ type: 'text', text: largeStaticInstructions, cache_control: { type: 'ephemeral' } },
{ type: 'text', text: dynamicContext }, // não cacheado
],
messages,
})
Hit rate >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 | <link rel="preconnect"> 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 <2s (Turbopack/Vite)
- Cold build aceitável (<60s pra projeto medio)
- CI build cache configurado
- Type check incremental (tsc --build se monorepo)
Profiling tools por stack
| Stack | Tool |
|---|---|
| Next.js bundle | @next/bundle-analyzer |
| React renders | React DevTools Profiler |
| Node.js | clinic.js, 0x flamegraphs |
| Postgres | pg_stat_statements, pgBadger, EXPLAIN ANALYZE |
| LLM cost | dashboard interno + Anthropic console |
| Web vitals | web-vitals package, Lighthouse, PageSpeed Insights |
| Network | Chrome DevTools Network tab, WebPageTest |
| Memory | Chrome DevTools Memory tab |
Output
PERF AUDIT
Projeto: [nome]
Profile alvo: [Local app / Internal SaaS / Public SaaS]
Pages/endpoints auditados: [lista]
FRONTEND BUNDLE
[Page]: X KB gzipped (alvo Y) — PASS/FAIL
Maiores chunks: [lista top 5]
FRONTEND RENDER
LCP: X (alvo <2.5s)
INP: X (alvo <200ms)
CLS: X (alvo <0.1)
BACKEND
[Endpoint]: p50 X ms, p95 Y ms, p99 Z ms — PASS/FAIL
DATABASE
Slow queries detectadas: [count]
Indexes faltando: [lista]
LLM (se aplicavel)
Cost por turn: $X (alvo Y)
Cache hit rate: X% (alvo >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).