Claude Code para investigações de desempenho: um fluxo medido

Por que o trabalho de performance dá errado sem medição

Bugs de desempenho convidam ao palpite. Alguém percebe que uma página parece lenta ou uma API dá timeout, e a reação rápida é "limpar" o código, adicionar cache ou reescrever um loop. O problema é que "parece lento" não é uma métrica, e "mais limpo" não é sinônimo de mais rápido.

Sem medição, equipes gastam horas mudando a coisa errada. O caminho crítico pode estar no banco de dados, na rede ou numa única alocação inesperada, enquanto a equipe polia código que quase não roda. Pior, uma mudança que parece inteligente pode piorar o desempenho: logs extras em um loop apertado, um cache que aumenta a pressão de memória, ou trabalho paralelo que cria contenção de locks.

Adivinhação também corre o risco de quebrar comportamento. Ao mudar código para acelerar, você pode alterar resultados, tratamento de erros, ordenação ou retries. Se você não verificar corretude e velocidade juntos, pode "ganhar" um benchmark enquanto envia silenciosamente um bug.

Trate performance como um experimento, não como um debate. O loop é simples e repetível:

• Escolha uma métrica que represente a dor (latência, throughput, CPU, memória, tempo de BD).
• Capture uma baseline sob as mesmas condições.
• Mude uma coisa pequena.
• Meça novamente e compare.

Muitos ganhos são modestos: cortar 8% do p95, reduzir pico de memória em 50 MB ou eliminar uma consulta ao banco. Esses ganhos importam, mas apenas se forem medidos, verificados e repetíveis.

O fluxo: medir, hipotetizar, mudar, re-medida

Isto funciona melhor como um loop, não como um pedido pontual de "deixar mais rápido". O loop te mantém honesto porque cada ação se liga a evidência e a um número que você pode observar.

Sequência clara:

• Medir: escolha uma métrica e registre uma baseline.
• Hipotetizar: explique o que você acha que está lento e por quê.
• Mudar: faça o menor ajuste possível que teste a hipótese.
• Re-medir: rode a mesma medição novamente e compare.

Cada passo te protege de um tipo diferente de autoengano. Medir primeiro impede que você "conserte" algo que não era um problema real. Uma hipótese escrita impede que você mude cinco coisas de uma vez e depois adivinhe qual delas importou. Mudanças mínimas reduzem o risco de quebrar comportamento ou adicionar novos gargalos. Re-medidas pegam ganhos placebo (como uma execução mais rápida por cache aquecido) e expõem regressões.

"Pronto" não é uma sensação. É um resultado: a métrica alvo se moveu na direção certa, e a mudança não causou regressões óbvias (erros, mais memória, pior p95 ou endpoints vizinhos mais lentos).

Saber quando parar também faz parte do fluxo. Pare quando os ganhos se achatam, quando a métrica já é boa o suficiente para os usuários, ou quando a próxima ideia exige grandes refactors por pouco ganho. Trabalho de performance sempre tem custo de oportunidade; o loop ajuda a gastar tempo onde vale a pena.

Escolha a métrica e fixe uma baseline

Se você medir cinco coisas ao mesmo tempo, não saberá o que melhorou. Escolha uma métrica primária para esta investigação e trate o resto como sinais de apoio. Para muitos problemas de interface, essa métrica é latência. Para jobs batch pode ser throughput, tempo de CPU, uso de memória ou até custo por execução na nuvem.

Seja específico sobre o cenário. "A API está lenta" é vago demais. "POST /checkout com um carrinho típico de 3 itens" é mensurável. Mantenha as entradas estáveis para que os números signifiquem algo.

Anote a baseline e os detalhes do ambiente antes de tocar no código: tamanho do dataset, tipo de máquina, modo de build, feature flags, concorrência e warmup. Essa baseline é sua âncora. Sem ela, qualquer mudança pode parecer progresso.

Para latência, confie em percentis, não só na média. p50 mostra a experiência típica, enquanto p95 e p99 expõem a cauda dolorosa que os usuários reclamam. Uma mudança que melhora p50 mas piora p99 ainda pode parecer mais lenta.

Decida de antemão o que "significativo" significa para não comemorar ruído:

• Latência: pelo menos 10% de melhoria no p95 (ou um limiar fixo como 50 ms)
• Throughput: pelo menos 5% mais requests por segundo com a mesma taxa de erro
• CPU ou memória: redução suficiente para evitar escalonamento ou crashes
• Custo: queda mensurável por execução ou por 1.000 requests

Com essas regras, você pode testar ideias sem mover o alvo.

Colete evidência com profiling e métricas simples

Comece pelo sinal mais fácil em que você confia. Um único timing em torno de uma requisição pode dizer se há um problema real e mais ou menos o tamanho dele. Reserve profiling mais profundo para quando precisar explicar por que está lento.

Boa evidência costuma vir de uma mistura de fontes:

• Logs do app (duração de requisição, taxa de erro, endpoints mais lentos)
• Traces APM (onde o tempo é gasto entre serviços)
• Saída do profiler ou flame graphs (funções quentes e pilhas de chamada)
• Estatísticas do banco (consultas lentas, esperas por locks, hit rate de cache)
• Métricas de infraestrutura (CPU, memória, rede, reinícios de container)

Use métricas simples quando a pergunta for "está mais lento, e quanto?" Use profiling quando a pergunta for "para onde o tempo está indo?" Se o p95 dobrou após um deploy, comece com timings e logs para confirmar a regressão e delimitar. Se os timings mostram que a maior parte do atraso está no código da sua aplicação (não no BD), então um profiler de CPU ou um flame graph pode apontar a função exata que cresceu.

Mantenha as medições seguras. Colete o que precisa para debugar performance, não conteúdo do usuário. Prefira agregados (durações, contagens, tamanhos) ao invés de payloads brutos, e redija identificadores por padrão.

Ruído é real, então faça várias amostras e note outliers. Rode a mesma requisição 10 a 30 vezes e registre mediana e p95 em vez de uma execução isolada.

Escreva a receita exata do teste para poder repeti-la após mudanças: ambiente, dataset, endpoint, tamanho do body, nível de concorrência e como você capturou resultados.

Transforme evidência em hipótese clara

Comece com um sintoma que você possa nomear: "p95 salta de 220 ms para 900 ms durante picos de tráfego", "CPU fica em 95% em dois núcleos" ou "memória cresce 200 MB por hora". Sintomas vagos como "parece lento" levam a mudanças aleatórias.

Depois, traduza o que você mediu para uma área suspeita. Um flame graph pode mostrar a maior parte do tempo em JSON encoding, um trace pode mostrar um caminho de chamada lento, ou estatísticas do BD podem mostrar uma consulta dominando o tempo total. Escolha a menor área que explique a maior parte do custo: uma função, uma única query SQL ou uma chamada externa.

Uma boa hipótese é uma frase, testável e ligada a uma previsão. Você está pedindo ajuda para testar uma ideia, não pedindo uma ferramenta para magicamente deixar tudo mais rápido.

Um template simples de hipótese

Use este formato:

• Por causa de (evidência), (suspeito) está causando (sintoma).
• Se mudarmos (comportamento específico), então (métrica) deve melhorar em (quantidade aproximada).
• Saberemos que funcionou se (resultado da re-medida).

Exemplo: "Porque o profile mostra 38% da CPU em SerializeResponse, alocar um buffer novo por requisição está causando picos de CPU. Se reutilizarmos um buffer, a latência p95 deve cair cerca de 10–20% e a CPU deve cair ~15% sob a mesma carga."

Mantenha-se honesto nomeando alternativas antes de tocar no código. Talvez a parte lenta seja uma dependência upstream, contenção de locks, mudança no hit rate do cache ou um rollout que aumentou o tamanho do payload.

Escreva 2 a 3 explicações alternativas e então escolha a que a evidência suporta melhor. Se sua mudança não mover a métrica, você já terá a próxima hipótese pronta.

Como usar Claude Code sem escorregar para a adivinhação

Claude é mais útil no trabalho de performance quando você o trata como um analista cuidadoso, não como um oráculo. Mantenha cada sugestão ligada ao que você mediu e garanta que cada passo possa ser provado falso.

Dê entradas reais, não descrições vagas. Cole evidências pequenas e focadas: um sumário de profiling, algumas linhas de log ao redor da requisição lenta, um plano de consulta e o caminho de código específico. Inclua números "antes" (latência p95, tempo de CPU, tempo de BD) para que ele saiba sua baseline.

Peça para explicar o que os dados sugerem e o que não suportam. Então force explicações concorrentes. Um prompt valioso termina com: "Dê 2–3 hipóteses e, para cada uma, diga o que a falsificaria." Isso evita que a equipe se prenda à primeira história plausível.

Antes de mudar qualquer coisa, peça o menor experimento que valide a hipótese principal. Mantenha-o rápido e reversível: adicione um timer ao redor de uma função, habilite uma flag de profiler, ou rode uma query com EXPLAIN.

Se quiser uma estrutura apertada para saída, peça por:

• O que a evidência indica (e confiança)
• 2–3 hipóteses com um teste de falseamento
• A menor mudança de código ou config para testar a principal
• Exatamente qual métrica re-medir e a direção esperada

Se não conseguir nomear uma métrica específica, localização e resultado esperado, você voltou a adivinhar.

Faça mudanças mínimas e reversíveis

Depois de ter evidência e hipótese, resista à vontade de "limpar tudo." Trabalho de performance é mais fácil de confiar quando a mudança de código é pequena e fácil de desfazer.

Mude uma coisa por vez. Se você ajustar uma query, adicionar cache e refatorar um loop no mesmo commit, não saberá o que ajudou (ou prejudicou). Mudanças de variável única tornam a próxima medição significativa.

Antes de tocar no código, anote o que você espera em números. Exemplo: "p95 deve cair de 420 ms para menos de 300 ms, e o tempo de BD deve cair ~100 ms." Se o resultado ficar aquém, você aprende rápido que a hipótese era fraca ou incompleta.

Mantenha as mudanças reversíveis:

• Prefira um diff pequeno que possa ser revertido limpo.
• Coloque a mudança atrás de uma flag simples para desligar rapidamente.
• Evite refactors de passagem que mudem nomes, formatação e lógica juntos.
• Mantenha o escopo apertado: um endpoint, um hot path, uma chamada cara.
• Adicione uma nota curta na mensagem do commit com as métricas esperadas antes/depois.

"Mínimo" não significa "trivial." Significa focado: cachear o resultado de uma função cara, remover uma alocação repetida num loop apertado, ou parar de fazer trabalho para requisições que não precisam.

Adicione timings leves ao redor do gargalo suspeito para ver o que se moveu. Um único timestamp antes e depois de uma chamada (logado ou capturado como métrica) pode confirmar se sua mudança atingiu a parte lenta ou apenas deslocou o tempo para outro lugar.

Re-meça e decida o próximo passo

Depois de uma mudança, rode exatamente o mesmo cenário que você usou para a baseline: mesmas entradas, ambiente e formato de carga. Se seu teste depende de caches ou warm-up, deixe isso explícito (por exemplo: "primeira execução fria, próximas 5 quentes"). Caso contrário você "encontrará" melhorias que foram apenas sorte.

Compare resultados usando a mesma métrica e os mesmos percentis. Médias podem esconder dor, então acompanhe p95 e p99, além de throughput e tempo de CPU. Rode repetições suficientes para ver se os números se estabilizam.

Antes de comemorar, cheque regressões que não aparecem num número de manchete:

• Corretude: respostas ainda batem com o esperado.
• Taxa de erro: timeouts, 5xx, retries.
• Memória: pico maior ou crescimento estável entre execuções.
• Latência de cauda: p99 piorou mesmo que p50 tenha melhorado.
• Custo de recurso: CPU ou carga do BD subiu.

Decida baseado em evidência, não em esperança. Se a melhoria for real e você não introduziu regressões, mantenha a mudança. Se os resultados forem mistos ou ruidosos, reverta e forme uma nova hipótese, ou isole ainda mais a alteração.

Se você trabalha em uma plataforma como Koder.ai, tirar um snapshot antes de experimentar pode transformar rollback em um único passo, o que facilita testar ideias ousadas com segurança.

Por fim, escreva o que aprendeu: baseline, mudança, novos números e conclusão. Esse registro curto evita que a próxima rodada repita os mesmos becos sem saída.

Erros comuns que desperdiçam tempo

O trabalho de performance costuma descarrilar quando você perde a linha entre o que mediu e o que mudou. Mantenha uma cadeia limpa de evidência para poder dizer, com confiança, o que fez as coisas melhorarem ou piorarem.

Os reincidentes:

• Consertar o alvo errado: comemorar uma mediana mais rápida (p50), mas a cauda (p95/p99) continua ruim.
• Mudar várias coisas de uma vez: refactors, caching e tweaks de query num único commit impedem saber o que ajudou.
• Acreditar em uma execução ruidosa: um benchmark local que varia 20% entre runs não é prova.
• Tratar um único profile como a verdade absoluta: um flame graph aponta para parsing JSON, mas requisições estão se acumulando por causa de lentidão no BD.
• Comparar maçãs com laranjas: datasets, feature flags, hardware ou níveis de concorrência diferentes, e ainda assim tirar conclusões.

Um exemplo pequeno: um endpoint parece lento, então você otimiza o serializer porque ele está quente num profile. Depois retesta com um dataset menor e parece mais rápido. Em produção o p99 piora porque o BD ainda era o gargalo e sua mudança aumentou o tamanho do payload.

Se usar Claude Code para propor correções, mantenha-o na coleira curta. Peça 1 a 2 mudanças mínimas que combinem com a evidência coletada e exija um plano de re-medir antes de aceitar um patch.

Uma checklist rápida antes de declarar “mais rápido”

Reivindicações de velocidade desmoronam quando o teste é vago. Antes de comemorar, certifique-se de que pode explicar o que mediu, como mediu e o que mudou.

Comece nomeando uma métrica e registrando a baseline. Inclua os detalhes que alteram números: tipo de máquina, carga de CPU, tamanho do dataset, modo de build (debug vs release), feature flags, estado do cache e concorrência. Se você não conseguir recriar o setup amanhã, você não tem uma baseline.

Checklist:

• Métrica e baseline registradas com notas de ambiente (hardware, config, dados, cache frio/feito).
• Passos do teste escritos e repetíveis.
• Você tem uma hipótese com previsão (por exemplo, "Se removermos queries N+1, p95 deve cair ~30%").
• Você fez uma mudança pequena e reversível e documentou exatamente o que moveu (arquivo, função, query, configuração).
• Re-me medições com múltiplas amostras e comparou igual com igual (mesmas entradas, mesma carga).

Depois que os números melhorarem, faça um rápido passe de regressão. Verifique corretude (mesmos outputs), taxa de erro e timeouts. Observe efeitos colaterais como mais memória, picos de CPU, startup mais lento ou mais carga no BD. Uma mudança que melhora p95 mas dobra memória pode ser um trade-off ruim.

Exemplo: investigando um endpoint de API lento passo a passo

Uma equipe relata que GET /orders parece ok em dev, mas fica lento em staging com carga moderada. Usuários reclamam de timeouts, mas a latência média ainda parece "ok", que é uma armadilha clássica.

Primeiro, defina uma baseline. Sob um teste de carga estável (mesmo dataset, mesma concorrência, mesma duração), você registra:

• p95 latency: 1.8s (alvo é < 600ms)
• CPU da API: ~70% com picos ocasionais
• BD: uma query está levando 900–1100ms, e o tempo total de query por requisição é ~1.3s

Agora colete evidência. Um trace rápido mostra que o endpoint roda uma query principal por orders, depois itera e busca itens relacionados por order. Você também nota que a resposta JSON é grande, mas o tempo do BD domina.

Transforme isso em uma lista de hipóteses testáveis:

• Uma query lenta precisa de um índice.
• Queries N+1 estão multiplicando o tempo de BD.
• Serialização é lenta por causa do payload grande.
• Contenção de locks está estagnando leituras durante writes.

Peça uma mudança mínima que combine com a evidência mais forte: remover uma chamada N+1 óbvia buscando os itens em uma única query com chave por order IDs (ou adicionar o índice faltante se o plano de execução mostrar scan completo). Mantenha reversível e em um commit focado.

Re-meça com o mesmo teste de carga. Resultados:

• p95 latency: 1.8s → 720ms
• Tempo total de BD: ~1.3s → 420ms
• CPU: um pouco menor, mas ainda com picos

Decisão: enviar a correção (ganho claro) e então iniciar um segundo ciclo focado na lacuna restante e nos picos de CPU, já que o BD não é mais o limitador principal.

Próximos passos: torne esse fluxo rotineiro

A maneira mais rápida de melhorar investigações de performance é tratar cada execução como um pequeno experimento repetível. Quando o processo é consistente, os resultados ficam mais fáceis de confiar, comparar e compartilhar.

Um template simples de uma página ajuda:

• Métrica + como é medida (ferramenta, comando, dataset)
• Baseline (números, ambiente e quando capturado)
• Hipótese (uma frase, testável)
• Mudança (diff pequeno, o que foi tocado)
• Resultado (antes/depois + decisão)

Decida onde essas notas vivem para que não desapareçam. Um lugar compartilhado importa mais que a ferramenta perfeita: uma pasta no repositório ao lado do serviço, um doc de time ou notas do ticket. O importante é que seja encontrável. Alguém deve conseguir achar "p95 spike após mudança de cache" meses depois.

Faça experimentos seguros um hábito. Use snapshots e rollback fácil para tentar ideias sem medo. Se você está construindo com Koder.ai, o Planning Mode pode ser um lugar conveniente para esboçar o plano de medição, definir a hipótese e manter a mudança no escopo antes de gerar um diff enxuto e re-medir.

Defina uma cadência. Não espere incidentes. Adicione checagens pequenas de performance após mudanças como novas queries, novos endpoints, payloads maiores ou upgrades de dependência. Um check de baseline de 10 minutos agora pode poupar um dia de adivinhação depois.