Como pedir para o Claude Code melhorar a performance quando você não tem métrica nenhuma?

"Otimiza isso aí" é o tipo de pedido que rende commit bonito e ponteiro parado

Você joga a frase na sessão, espera, e volta com um punhado de renomeação, um memo solto, um loop trocado por reduce, e a tela continuando a demorar exatamente o mesmo tanto pra pintar

O cenário real é esse: você SENTE que tá lento, não tem profiler configurado, não tem número nenhum e nem sabe direito onde dói

A boa notícia é que dá pra escrever um pedido de performance decente sem métrica na mão

O truque não é adivinhar o gargalo, é descrever o sintoma e o caminho, e mandar medir ANTES de mexer em código

Bora montar isso? 😀

O que você precisa ter antes de pedir

Não é ferramenta paga, não é dashboard, não é APM

São três coisas bem simples:

• Um caminho reproduzível até a lentidão: a tela, a rota, o comando, o clique. Se você consegue repetir, dá pra medir
• O projeto acessível na sessão do Claude Code: ele precisa enxergar os arquivos que você vai citar no pedido
• A ferramenta Bash disponível, que é a que executa comandos de shell na sessão e consta na referência oficial de ferramentas

E o que você NÃO precisa: profiler configurado, benchmark prévio, número de baseline, nada disso

Também não vou te passar comando mágico de auditoria de performance, dessas coisas toscas que aparecem por aí

A medição vem de um comando do SEU projeto, aquele que você já roda pra buildar, testar ou subir a aplicação

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Como montar o pedido de performance passo a passo

1. Descreva o sintoma, sem adjetivo vago

"Lento" não é sintoma, é opinião

Sintoma é o que você observa acontecendo: a lista fica em branco por um tempo antes de aparecer, o botão fica travado depois do clique, o terminal para numa etapa e não sai dali

Quando eu abro /pedidos, a tabela fica em branco por um tempo
visível antes de renderizar. O spinner aparece, some, e aí
tem mais uma pausa até as linhas pintarem na tela.

O erro comum deste passo: trocar "lento" por "muito lento" e achar que descreveu alguma coisa

2. Descreva o caminho do usuário até o ponto lento

O modelo não viu você clicando

Então conta o percurso: onde você entra, o que faz, em que momento exato a lentidão aparece, e se ela some ao repetir (cache é traiçoeiro, se liga nisso)

Caminho: login > menu lateral > Pedidos > filtro "últimos 30 dias".
A pausa acontece depois de aplicar o filtro, não no carregamento
inicial. Se eu reaplico o mesmo filtro, a segunda vez parece mais rápida.

O erro comum deste passo: descrever só a tela final e esquecer que o gargalo pode estar duas telas antes

3. Aponte arquivos e restrições

A documentação oficial de boas práticas do Claude Code é bem direta nesse ponto: quanto mais precisa a instrução, menos correção você vai precisar fazer depois

Ela recomenda citar arquivos específicos, mencionar restrições e apontar padrões de exemplo, porque o Claude consegue inferir intenção, mas não consegue ler a sua mente

Os arquivos envolvidos são app/pedidos/page.tsx e lib/pedidos/query.ts.
Restrições: não mudar o schema do banco, não trocar de biblioteca de
tabela, manter o filtro funcionando igual. Siga o padrão de query que
já existe em lib/clientes/query.ts.

O erro comum deste passo: mandar ele "olhar o projeto inteiro" e esperar que ele adivinhe o que é intocável

4. Peça medição ANTES de otimização

Esse é o passo que muda o jogo

Você não tem número, então a primeira tarefa não é mudar código, é PRODUZIR o número

E isso você pede explicitamente, junto com o comando que gera a medida

Antes de alterar qualquer linha, quero medição. Rode o comando que eu
já uso pra esse fluxo, colete o tempo, e me mostre onde ele se concentra.
Depois me diga qual é a sua hipótese de gargalo e como você pretende
confirmar que ela é verdadeira. Só depois disso proponha mudança.

Repare que aqui você está pedindo comportamento, não torcendo pra ele adivinhar

A documentação de prompting da Anthropic fala isso com todas as letras: se você quer um comportamento acima do básico, peça explicitamente em vez de contar que o modelo infira a partir de prompt vago

O erro comum deste passo: pedir a medição e aceitar de volta uma estimativa em texto no lugar de uma execução de verdade

5. Entre em plan mode pra receber um plano sem edição

O plan mode manda o Claude pesquisar e propor mudanças sem fazê-las, usando ferramentas somente leitura pra analisar o código e devolver um plano detalhado

Você entra com Shift+Tab, ou prefixa um prompt único com /plan

Se quiser voltar pro plan mode depois, é só ciclar de novo com Shift+Tab

É o oposto do modo acceptEdits, que deixa o Claude criar e editar arquivo no diretório de trabalho sem pedir confirmação e ainda auto-aprova comandos comuns de sistema de arquivos como mkdir, touch, rm, rmdir, mv, cp e sed

Pra um pedido de performance sem métrica, você quer justamente o contrário: quer VER a proposta antes de qualquer arquivo mudar

O erro comum deste passo: começar já em modo de edição e descobrir o gargalo depois de três arquivos alterados

6. Revise o plano e só então aprove

O plano proposto pode ser aberto no seu editor de texto padrão com Ctrl+G, pra você editar direto antes do Claude prosseguir

Usa isso: corta o passo que não faz sentido, escreve a restrição que você esqueceu, marca o que é pra medir de novo no fim

E atenção aqui: aprovar o plano encerra o plan mode e muda a sessão pro modo de permissão descrito na opção de aprovação que você escolheu, ou seja, a partir dali ele começa a editar

O erro comum deste passo: aprovar no automático e só perceber depois que o plano tinha um "refatorar o módulo inteiro" escondido no meio

Por que pedir só "otimize" rende mudança cosmética

O sintoma

Você pede pra otimizar e recebe de volta uma coleção de coisas defensáveis: variável renomeada, função quebrada em duas, um memo aplicado num componente que renderiza duas vezes por sessão

Tudo isso é "melhor" em algum sentido abstrato

E nada disso move o ponteiro do que te incomodava

A causa

Sem alvo declarado, o modelo precisa inferir o que "melhor" significa

E "melhor" pode ser legível, pode ser idiomático, pode ser menos linhas, pode ser mais rápido

Ele escolhe uma leitura, e a chance de bater com a sua é uma loteria

A Anthropic tem uma analogia boa pra isso: pensa no Claude como um funcionário brilhante mas novo, que não tem contexto nenhum sobre as suas normas e os seus fluxos de trabalho

O cara é fera, só não sabe que na sua casa "tá lento" quer dizer especificamente aquela tabela filtrada

A solução

Troca o adjetivo pelo sintoma, e a opinião pela medição

Como prevenir

A documentação de prompting da Anthropic tem uma régua de ouro que resolve isso antes de mandar o prompt

Mostra o seu pedido pra um colega que tem pouco contexto da tarefa e pede pra ele seguir

Se a pessoa se confundir, o Claude também vai se confundir

Faça o teste com o seu próximo pedido de performance, é meio constrangedor a primeira vez haha

Três situações reais e o pedido que cabe em cada uma

São essas três: tela que demora a pintar, comando de build ou teste que arrasta, e resposta de API que parece travar

O esqueleto é o mesmo nas três, muda só o que você observa e o que manda medir

1. Tela que demora a pintar

Descreva onde você entra, qual interação dispara a pausa, e o que você vê durante ela (branco? spinner eterno? conteúdo aparecendo em pedaços?)

O que pedir pra medir: o tempo do fluxo completo, do clique até o conteúdo na tela, e onde ele se concentra

A tela X demora a pintar depois que eu aplico o filtro. Fica branco,
depois vem tudo de uma vez. Antes de mudar código: rode o app, percorra
esse caminho, meça o tempo do clique até o conteúdo visível e me diga
qual trecho responde pela maior parte dele. Não altere nada ainda.

2. Comando de build ou teste que arrasta

Aqui você já tem o comando, o que é meio caminho andado

Descreva em que etapa ele parece parar e se isso mudou depois de alguma alteração recente

O que pedir pra medir: o tempo por etapa do comando, pra achar qual delas come a maior fatia

O comando de build que eu uso nesse projeto arrasta numa etapa
específica. Rode ele, colete o tempo por etapa e me mostre a
distribuição. Depois me dê a sua hipótese e como confirmá-la.
Só proponha mudança depois disso.

3. Resposta de API que parece travar

Esse é o mais escorregadio, porque "travar" pode ser fila, pode ser query, pode ser rede

Descreva o payload, o parâmetro que parece piorar tudo, e se acontece sempre ou só com dado grande

O que pedir pra medir: os dois cenários lado a lado, com e sem o parâmetro suspeito, pra diferença aparecer sozinha

O endpoint X parece travar quando o parâmetro Y vem preenchido. Com Y
vazio, a resposta parece normal. Antes de otimizar: rode o endpoint nos
dois cenários, meça e compare, e me diga onde está a diferença. Arquivos
envolvidos: (liste aqui). Não mude schema.

Repare o padrão nos três: caminho, momento em que a lentidão aparece, o que você observa, e a medição pedida ANTES da mudança

Nenhum número inventado, nenhum chute de gargalo

Quando o pedido vago vale a pena (e como corrigir o rumo)

Agora o contraponto honesto, porque prompt vago não é pecado sempre

A própria documentação do Claude Code reconhece que pedidos vagos são úteis quando você está explorando e pode corrigir o rumo depois, e dá até o exemplo clássico: "o que você melhoraria neste arquivo?"

O problema nunca foi o vago, foi usar o vago como EXECUÇÃO

1. Use o vago como reconhecimento

Abre a sessão, joga o "o que você melhoraria aqui?", lê o que vem, e trata aquilo como mapa, não como ordem de serviço

2. Use o específico como execução

Pega o que apareceu no reconhecimento, transforma em sintoma + caminho + medição, e aí sim entra em plan mode

Isso encaixa direitinho no fluxo explore, plan, code, commit, que é documentado no Claude Academy

O explore é onde o vago cabe, o plan é onde ele deixa de caber

3. Separe as sessões

Esse aqui pouca gente faz e faz diferença

A Anthropic é explícita: a janela de contexto do Claude enche rápido, e o desempenho degrada conforme ela enche, e boa parte das boas práticas nasce justamente dessa restrição

Se você gastou meia sessão explorando, o momento de executar é o pior possível

Exploração numa sessão, execução em outra, com o pedido específico já escrito

E tem hora que nem é caso de pedido nenhum: existe lentidão que você resolve em dois minutos na mão, e vale a mesma régua de fazer na mão sai mais rápido

O erro comum aqui: usar a resposta do prompt exploratório como se fosse plano aprovado e sair editando

O próximo passo

A régua toda cabe em três palavras: sintoma, caminho, medição

Sintoma é o que você observa, não o adjetivo que você sente

Caminho é o percurso reproduzível até ele

Medição é o número que ainda não existe e que o Claude vai produzir ANTES de tocar em código

O próximo passo prático é o mais fácil: na próxima lentidão que aparecer, não jogue o "otimiza isso aí"

Escreve o pedido nos moldes daqui, entra em plan mode com Shift+Tab, revisa o plano com Ctrl+G e guarda o plano aprovado como referência pro próximo caso parecido

Depois de dois ou três, você já tem um formato pronto pra colar

E pra quem quer ir além, a Anthropic mantém um material oficial sobre otimizar performance de código com o Claude

Até o próximo post! =)