Otimização de performance com Claude Code: métricas e Core Web Vitals

Otimização de performance não é deixar uma aplicação “parecer mais rápida” de forma genérica. É medir o que o usuário espera, o que bloqueia uma interação, o que desloca o layout e o que desperdiça recursos no servidor, para então reduzir esses custos com mudanças pequenas e verificáveis.

Claude Code ajuda porque consegue ler o código, investigar gargalos prováveis, sugerir patches e escrever passos de validação. O fluxo correto é medir, criar uma hipótese, alterar uma coisa e medir de novo com a mesma ferramenta.

Use as referências oficiais: web.dev Core Web Vitals, Lighthouse docs e MDN Performance API.

Defina O Que É Rápido

Performance web não é uma nota única. LCP, Largest Contentful Paint, mede quando o conteúdo principal aparece. INP, Interaction to Next Paint, mede a resposta depois de clique, toque ou digitação. CLS, Cumulative Layout Shift, mede deslocamentos inesperados do layout.

Em uma aplicação, também importam latência p75 de API, número de consultas ao banco, tamanho do bundle JavaScript, peso das imagens e trabalho síncrono no navegador. A média esconde usuários lentos; p75 costuma representar melhor a experiência real da maioria.

flowchart LR
  Measure["Medir"] --> Hypothesis["Criar hipótese"]
  Hypothesis --> Patch["Alterar pouco"]
  Patch --> Verify["Medir de novo"]
  Verify --> Keep["Manter o comprovado"]

Métrica	Significado	Primeiro alvo
LCP	Conteúdo principal visível	2.5s ou menos
INP	Resposta a interações	200ms ou menos
CLS	Movimento inesperado	0.1 ou menos
API p75	Latência percebida por muitos usuários	Definir por tela
JS transferido	JavaScript carregado no início	Comparar por rota

Dê Bons Dados Ao Claude Code

Uma boa solicitação inclui sintoma, reprodução, números atuais e restrições.

A página /products deste repositório está lenta.
O objetivo é reduzir o LCP móvel e o p75 de /api/products.

Medições atuais:
- Lighthouse mobile Performance: 58
- LCP: 4.2s
- INP: 180ms
- CLS: 0.04
- /api/products p75: 920ms

Por favor:
1. Revise imagens, bundle, API e acesso ao banco.
2. Não altere código só por suposição; mostre arquivos e evidências.
3. Priorize mudanças pequenas e mensuráveis.
4. Inclua os comandos de verificação.

Para complementar, veja o guia de depuração Claude Code, React com Claude Code e o guia de otimização de imagens.

Script Executável De Medição

Com Node.js 18 ou superior, este script mede uma página ou API e mostra média e p75.

// measure-url.mjs
import { performance } from "node:perf_hooks";

const url = process.argv[2] ?? "https://example.com/";
const runs = Number(process.argv[3] ?? 5);

async function measureOnce() {
  const start = performance.now();
  const res = await fetch(url, { cache: "no-store" });
  await res.arrayBuffer();
  return {
    status: res.status,
    ms: performance.now() - start,
  };
}

const samples = [];
for (let i = 0; i < runs; i += 1) {
  samples.push(await measureOnce());
}

samples.sort((a, b) => a.ms - b.ms);
const avg = samples.reduce((sum, s) => sum + s.ms, 0) / samples.length;
const p75Index = Math.floor((samples.length - 1) * 0.75);
const p75 = samples[p75Index].ms;

console.table(
  samples.map((sample, index) => ({
    run: index + 1,
    status: sample.status,
    ms: sample.ms.toFixed(1),
  }))
);
console.log(`avg=${avg.toFixed(1)}ms p75=${p75.toFixed(1)}ms`);

node measure-url.mjs http://localhost:3000/api/products 7

Use essa saída antes e depois do patch. Assim a discussão vira comparação repetível, não impressão subjetiva.

Casos De Uso Reais

Caso	Causa comum	O que pedir ao Claude Code
Dashboard SaaS lento	Todos os widgets carregam no início; biblioteca de gráficos pesada	Adiar widgets secundários e separar código dos gráficos
Lista de e-commerce lenta	Imagens grandes e N+1 em estoque ou avaliações	Corrigir imagens e revisar include/select
Artigo com LCP ruim	Imagem principal chega tarde; scripts de anúncios cedo demais	Priorizar a imagem principal e adiar terceiros
Busca admin travando	Filtro síncrono em arrays grandes	Reduzir complexidade, paginar ou mover trabalho

N+1 significa buscar uma lista e depois executar uma consulta extra para cada item. Cache significa reutilizar um resultado por pouco tempo, mas dados pessoais, permissões, preços e estoque exigem chave, TTL e invalidação corretos.

Exemplo Executável De Cache

Este exemplo Express compara uma API propositalmente lenta com outra cacheada. Em produção, Redis ou CDN são comuns, mas memória local mostra bem o comportamento.

npm init -y
npm install express
node cached-api.mjs

// cached-api.mjs
import express from "express";
import { performance } from "node:perf_hooks";

const app = express();
const cache = new Map();
const ttlMs = 30_000;

async function loadProducts() {
  await new Promise((resolve) => setTimeout(resolve, 800));
  return [
    { id: 1, name: "Starter Plan", price: 1200 },
    { id: 2, name: "Pro Plan", price: 4800 },
  ];
}

async function cached(key, loader) {
  const now = Date.now();
  const hit = cache.get(key);
  if (hit && hit.expiresAt > now) return { data: hit.data, cache: "hit" };

  const data = await loader();
  cache.set(key, { data, expiresAt: now + ttlMs });
  return { data, cache: "miss" };
}

app.get("/api/products/raw", async (_req, res) => {
  const start = performance.now();
  const data = await loadProducts();
  res.json({ cache: "none", ms: performance.now() - start, data });
});

app.get("/api/products/cached", async (_req, res) => {
  const start = performance.now();
  const result = await cached("products", loadProducts);
  res.json({ ...result, ms: performance.now() - start });
});

app.listen(3000, () => {
  console.log("Open http://localhost:3000/api/products/raw");
});

node measure-url.mjs http://localhost:3000/api/products/raw 3
node measure-url.mjs http://localhost:3000/api/products/cached 3

Ao pedir cache, defina o escopo: produtos populares por 30 segundos, estoque sem cache, dados de usuário com userId na chave.

Exemplo Executável De Algoritmo

Nem todo gargalo está na rede. JavaScript síncrono pesado pode piorar INP. Aqui, buscas repetidas com includes viram um Set.

// compare-lookup.mjs
import { performance } from "node:perf_hooks";

const a = Array.from({ length: 40_000 }, (_, i) => i);
const b = Array.from({ length: 40_000 }, (_, i) => i * 2);

function slowIntersection(left, right) {
  return left.filter((item) => right.includes(item));
}

function fastIntersection(left, right) {
  const rightSet = new Set(right);
  return left.filter((item) => rightSet.has(item));
}

function time(label, fn) {
  const start = performance.now();
  const result = fn();
  const ms = performance.now() - start;
  console.log(`${label}: ${ms.toFixed(1)}ms (${result.length} hits)`);
}

time("slow", () => slowIntersection(a, b));
time("fast", () => fastIntersection(a, b));

node compare-lookup.mjs

Erros Comuns

Não otimize apenas para Lighthouse. Lighthouse é laboratório; usuários reais têm aparelhos, redes e cache diferentes. Combine com Search Console, RUM e logs do servidor.

Não adicione cache sem regras de correção. Preço, estoque, permissão e dados pessoais precisam de chave, TTL e invalidação.

Não use useMemo em tudo. Memoização em React deve proteger pontos quentes medidos, não complicar o código inteiro.

Não priorize todas as imagens. Imagens acima da dobra precisam de tamanho estável e talvez prioridade; imagens abaixo geralmente devem continuar lazy.

Não divida bundles às cegas. Use análise de bundle com Claude Code e code splitting com Claude Code para comparar impacto por rota.

Regras Para CLAUDE.md

## Performance rules
- Before optimizing, record the current metric and target metric.
- Prefer small, measurable changes over broad rewrites.
- Do not introduce shared cache for user-specific data.
- Avoid N+1 queries; use select/include or batching.
- Keep above-the-fold images sized and stable.
- After changes, report commands used for verification.

Essas regras mantêm Claude Code focado em melhorias comprováveis.

CTA De Consultoria

ClaudeCodeLab pode ajudar a auditar aplicações web com Claude Code, melhorar Core Web Vitals, separar latência de API/DB e criar um runbook prático. Para a primeira análise, prepare URL, telas principais, resultado do Lighthouse, logs de APIs lentas e prazo desejado.

Resultado Verificado

Executando localmente, /api/products/raw fica perto de 800ms por causa do atraso intencional, enquanto /api/products/cached cai para poucos milissegundos após a primeira requisição. compare-lookup.mjs também mostra ganho claro com Set. Em projetos reais os números variam, mas o método funciona: medir p75, mudar uma coisa e medir novamente.