5 erros comuns de quem começa a usar o Claude Code (e o que fazer no lugar)

Fala aí, beleza? Se as primeiras semanas com o Claude Code te deram mais retrabalho do que resultado, respira: na maioria das vezes a ferramenta não está fraca, o uso é que está torto

Os cinco erros aqui embaixo são de rota, não de talento

E o melhor: cada um tem correção documentada, curtinha e de graça, quase sempre um comando ou um arquivo de meia dúzia de linhas 🙂

Bora consertar?

Erro 1: pedir sem dar contexto do projeto

O sintoma é fácil de reconhecer: resposta genérica, comando de build errado, convenção do time solenemente ignorada

Você sabe o padrão da casa, o agente não

A correção é o CLAUDE.md, o arquivo de memória que o Claude Code carrega automaticamente no início de cada sessão, e onde moram comandos de build, instruções de teste e convenções do projeto

1. Rode o /init na raiz do projeto: ele analisa a base de código e gera um CLAUDE.md inicial

/init

2. Se já existe um CLAUDE.md ali, relaxa, o /init não sobrescreve: ele sugere melhorias

3. Escolha o lugar do arquivo de projeto, que pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md

4. O que vale pra TODOS os seus projetos vai no escopo global, em ~/.claude/, que no Windows corresponde a %USERPROFILE%\.claude

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

./CLAUDE.md
./.claude/CLAUDE.md
~/.claude/

5. Segure o tamanho: a documentação recomenda manter cada CLAUDE.md abaixo de 200 linhas, porque arquivo mais longo consome mais contexto e reduz a aderência às instruções

6. Quando as instruções crescerem demais mesmo assim, a saída oficial são as regras com escopo de caminho (path-scoped rules), que só carregam quando o Claude trabalha em arquivos que casam com o padrão

O erro comum deste passo: despejar o projeto inteiro no arquivo achando que quanto mais, melhor

Aí acontece o contrário: o arquivo engorda, come contexto e o modelo passa a seguir menos o que tu escreveu

Erro 2: deixar a mesma sessão inchar até o fim do dia

Sintoma clássico: o Claude esquece uma instrução que você deu há pouco, e você jura que ele ficou burro do nada

Não ficou

A janela de contexto guarda a conversa inteira, incluindo cada mensagem, cada arquivo lido e cada saída de comando, e o desempenho degrada conforme ela enche

1. Antes de culpar o modelo, olhe o painel: o /context mostra a divisão ao vivo do uso do contexto por categoria, com sugestões de otimização, e ainda lista quais arquivos CLAUDE.md e de memória foram carregados

/context

2. Trocou de assunto? Zere: o /clear inicia uma nova sessão e limpa o histórico de entrada, e é o recomendado entre tarefas não relacionadas

3. Quando você quer continuar a mesma tarefa mas o espaço acabou, use o /compact, que resume o contexto pra liberar espaço e aceita instruções sobre o que preservar no resumo

/compact mantenha as decisões de arquitetura e o passo a passo do deploy

4. Saiba que existe rede automática: as sessões compactam sozinhas antes de a janela encher, em cerca de 967 mil tokens por padrão, e esse limiar pode ser mudado pela variável CLAUDE_CODE_AUTO_COMPACT_WINDOW

O erro comum deste passo: pedir investigação sem escopo, aquele "dá uma olhada geral no projeto"

Isso faz o Claude ler centenas de arquivos e encher o contexto antes mesmo de começar o trabalho de verdade

A correção documentada é delimitar a investigação ou jogar ela pra um subagente, que começa com uma janela de contexto nova e isolada, não vê o histórico da conversa nem os arquivos já lidos, e devolve só o resumo relevante pra conversa principal

Erro 3: mandar editar antes de combinar o que vai ser feito

Sintoma: você pediu um ajuste pequeno e recebeu uma refatoração gigante que ninguém encomendou 😅

A correção tem nome: modo plano (plan mode)

Nele o Claude lê arquivos, roda comandos de exploração somente leitura, escreve um plano e NÃO edita o código-fonte

De quebra, no modo plano ele delega a pesquisa da base de código ao subagente de plano, então toda aquela saída de exploração fica em uma janela de contexto separada e não suja a sua conversa

1. No CLI, pressione Shift+Tab pra alternar entre os modos, no ciclo default → acceptEdits → plan

2. Escreva o pedido já dentro do plan mode, descrevendo o objetivo e o limite (o que pode e o que não pode mexer)

3. Leia o plano linha por linha e corrija o que estiver fora do combinado, ainda no modo plano

4. Só depois saia do modo pra execução começar

Se o problema é daqueles cabeludos, vale combinar isso com extended thinking no Claude Code pra ele raciocinar mais antes de propor o caminho

O erro comum deste passo: aprovar o plano sem ler

Aí o plan mode vira teatro: você adicionou uma etapa e não ganhou nada em troca

Erro 4: aprovar tudo no automático e nunca olhar o diff

Sintoma: tudo verde, tudo aceito, e o bug aparece três dias depois num arquivo que você nem lembrava que foi tocado

Primeiro, entenda os modos de permissão do Claude Code, controlados pela configuração defaultMode:

Duas leituras importantes dessa tabela

O acceptEdits é indicado pra quem prefere revisar as mudanças DEPOIS, no editor ou no git diff, e não aprovar cada edição na hora

Já o bypassPermissions a documentação orienta usar apenas em ambientes isolados, tipo contêiner ou máquina virtual, onde o Claude Code não consegue causar dano

Se revisar depois é o seu estilo, vale amarrar isso ao versionamento e usar o Claude Code junto com o Git pra cada bloco de mudança virar commit e ficar fácil de ler

E existe uma rede de segurança embutida

1. O checkpointing captura automaticamente o estado do código antes de cada prompt do usuário

2. Pra abrir o menu de rewind, rode /rewind ou pressione Esc duas vezes com o campo de entrada vazio

/rewind

3. O menu te dá quatro ações: restaurar código e conversa, restaurar só a conversa, restaurar só o código, ou resumir a partir daquele ponto

4. Escolha a ação e continue dali, sem precisar reconstruir a sessão do zero

O erro comum deste passo: achar que o rewind substitui commit

Não substitui: o Claude Code guarda snapshots dos 100 checkpoints mais recentes da sessão, e o checkpointing não reverte arquivos que são symlink ou hard link

Tome cuidado com isso, é o tipo de detalhe que só machuca no pior dia possível

Erro 5: achar que escrever a regra no CLAUDE.md garante que ela seja seguida

Sintoma: tem um belo "rode o lint antes de terminar" no CLAUDE.md e o lint… não roda

O porquê é simples: instrução de CLAUDE.md é orientativa

Quando a regra é inegociável, o instrumento certo são os hooks, que são comandos de shell definidos por você e rodados pelo Claude Code em pontos específicos do ciclo de vida, dando controle determinístico

1. Configure editando o .claude/settings.json

2. Confira o que está no ar com o /hooks, que lista os hooks configurados agrupados por evento

/hooks

3. Escolha o evento com atenção, porque cada um tem seu comportamento

4. Se for usar o Stop, saiba que ele dispara sempre que o Claude termina de responder, não apenas na conclusão da tarefa, e não dispara quando você interrompe

5. Se for usar o PostToolUse, entenda o limite: ele não desfaz ações, porque a ferramenta já executou

O erro comum deste passo: montar um hook esperando que ele funcione como "desfazer"

Hook é controle e verificação, não máquina do tempo

Ah, e se você quer que o Claude vá guardando memória sozinho, a alternância de memória automática fica no comando /memory, e a preferência é salva como autoMemoryEnabled nas configurações do usuário em ~/.claude/settings.json

Que modo usar em cada tipo de tarefa

Bloco de decisão rápido, pra você não ter que reler o post inteiro na hora do aperto

E lembra do atalho: Shift+Tab alterna entre os modos, no ciclo default → acceptEdits → plan

O bypassPermissions ficou fora da tabela de propósito: a documentação orienta usar ele apenas em ambiente isolado, tipo contêiner ou máquina virtual

É pouca coisa, mas muda o dia inteiro, sério

O que a gente viu rodando isso de verdade

Quando testei, criando um projeto do zero, a rodada de tarefas iniciais levou quase meia hora

E teve um detalhe que casa direto com o Erro 4: duas tarefas apareceram como pendentes no fim, e na verificação já estavam prontas

Bug visual da lista, nada de grave, mas olha o tamanho da armadilha

Se eu tivesse tratado a listinha de tarefas do agente como verdade, teria mandado refazer coisa que já estava feita

A régua é o git diff e o estado real do código rodando, não o painel que o agente exibe

Foi assim que fechei a validação naquele teste: abri a aplicação, criei o registro, publiquei, cliquei e confirmei que os dados persistiram na mão

E, sim, apanhei de um erro logo na primeira abertura do projeto e tive que pedir correção, o que só reforça a régua: código rodando é a prova 😀

Vídeo: o teste completo

No vídeo abaixo eu mostro a rodada inteira: o projeto nascendo do zero, o comportamento do agente durante a execução e exatamente o que exigiu revisão minha no fim

Por onde começar a corrigir a rota hoje

Se você só vai fazer três coisas depois de ler isso aqui, faça estas

1. Rode o /init no projeto que você está mexendo agora e ajuste o CLAUDE.md gerado, lembrando do teto recomendado de 200 linhas

2. Dê um /context uma vez no meio da sessão, só pra enxergar pra onde o seu contexto está indo

3. Use o /clear toda vez que trocar de tarefa, principalmente quando a nova não tem nada a ver com a anterior

Hooks, path-scoped rules e subagente são o próximo degrau, e valem muito

Mas deixa eles pra depois que essa rotina básica estiver de pé, senão você automatiza um processo torto e o resultado piora

Corrigiu a rota, o resto flui…

até o próximo post!