7 erros comuns de quem começa no Claude Code (e como corrigir cada um)

O Claude Code raramente falha por falta de capacidade

Ele falha porque a pessoa do outro lado do terminal está pilotando no modo "joga o pedido e torce"

Fala aí, beleza? Os sete erros abaixo não são bug nem limitação do modelo: são erro de configuração e de fluxo de trabalho, e cada um tem uma correção que JÁ existe pronta dentro da ferramenta, é só saber onde ela mora

Aqui não tem "prompt mágico" nem achismo: tudo apoiado no comportamento documentado dos comandos e dos modos de permissão. Se você quiser ver por outro ângulo depois, tem também esta lista de erros comuns de quem começa aqui no blog

Bora corrigir?

O que você precisa antes de aplicar as correções

Nada de PC da Nasa, se liga:

• uma sessão do Claude Code aberta no terminal, dentro da pasta do projeto
• o projeto versionado em Git

O Git não está aí de enfeite

Uma das sete correções depende dele por um motivo específico: o checkpoint interno do Claude Code não substitui controle de versão, e isso fica explícito no Erro 6 🙂

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

Erro 1: pedir uma mudança gigante de uma vez, sem plano

Sintoma: você manda "refatora o módulo inteiro" e volta um monte de edição espalhada por vários arquivos, difícil de auditar linha por linha

Causa: o modelo começou a editar ANTES de você concordar com o caminho. Não teve momento de discordar

Solução: plan mode

O plan mode faz o Claude pesquisar e propor mudanças sem executá-las: ele lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte

Ele é read-only e exige aprovação do plano antes de qualquer edição

Como entrar? Durante a sessão, Shift+Tab cicla entre os modos de permissão, nesta ordem:

default (manual) → acceptEdits → plan

Tome cuidado: apertar Shift+Tab de novo dentro do plan mode SAI do plan mode sem aprovar o plano. Se você fizer isso achando que está confirmando, o plano some e você volta pro ciclo

Como prevenir: a tela de aprovação do plano é o seu momento de fatiar o pedido. Leu o plano e ele tem seis etapas? Aprove o caminho pensando em entregar por partes, não em um mega commit só

Erro 2: não revisar o diff e aprovar tudo no automático

Sintoma: o código muda, os testes quebram e ninguém sabe qual edição causou o estrago

Aí o trabalho vira caçar bug do zero, e aí entra outro assunto: diagnosticar e corrigir bugs com IA é um fluxo à parte, que você preferia não precisar

Causa: modo de permissão errado pro SEU jeito de revisar

Solução: escolher o modo de propósito, não por acaso

O acceptEdits é indicado justamente pra quem prefere revisar as mudanças depois, no editor ou via git diff, em vez de aprovar cada edição na hora

Como prevenir: o pecado não é escolher acceptEdits, é ficar nos dois modos ao mesmo tempo MENTALMENTE

Ou seja: aceitar rápido como se fosse revisar depois, e depois nunca abrir o diff 😛

Erro 3: ignorar o contexto do projeto e explicar tudo no prompt

Sintoma: você repete comando de build, padrão de código e convenção de nome em TODO prompt, e ainda assim recebe código fora do padrão da casa

Causa: falta de CLAUDE.md

Solução: deixar o projeto se apresentar sozinho

Se você conhece aquele README que todo mundo do time lê antes de commitar, o CLAUDE.md é o primo dele voltado pro Claude

1. Rode o comando que gera o arquivo inicial automaticamente:

/init

O erro comum deste passo: gerar o arquivo e nunca mais olhar pra ele. O /init te dá o ponto de partida, não a verdade final do projeto

2. Confirme onde ele ficou. Os caminhos válidos são ./CLAUDE.md ou ./.claude/CLAUDE.md

3. Escreva ali o que vale pra QUALQUER pessoa do projeto: comandos de build e teste, padrões de código, decisões de arquitetura, convenções de nome e fluxos comuns

E tem um detalhe que muda o resultado na prática

Os arquivos CLAUDE.md e CLAUDE.local.md que estão na hierarquia de diretórios ACIMA do diretório de trabalho são carregados por inteiro no início da sessão

Já os que estão em subdiretórios carregam sob demanda, quando o Claude lê arquivos daquele diretório

Ou seja: regra de submódulo pode morar perto do submódulo, que ela aparece na hora certa

Como prevenir: o que é regra do time vai pro arquivo, não pro chat. Chat some, arquivo fica

Erro 4: corrigir a mesma preferência em toda sessão nova

Sintoma: semana após semana você corrige o mesmo detalhe de estilo ou de fluxo. Toda sessão nova, mesma ladainha

Causa: tratar toda memória como manual, como se o único jeito fosse você escrever cada regra na mão

Solução: além do CLAUDE.md, existe a auto memory

São notas que o próprio Claude escreve a partir das suas correções e preferências

Ela vem ligada por padrão

O toggle fica no comando /memory, dentro da sessão, e ele grava autoMemoryEnabled no ~/.claude/settings.json

Como prevenir: divida o trabalho. Regra do projeto (build, arquitetura, convenção) vai no CLAUDE.md; preferência recorrente sua, aquela que aparece na correção do dia a dia, deixa a auto memory capturar

Erro 5: arrastar a mesma conversa até ela ficar lenta e confusa

Sintoma: as respostas começam a misturar assunto antigo com o atual, e a sessão vai ficando pesada

Causa: histórico acumulado sem nenhuma gestão. Você abriu a sessão na segunda e ainda está nela na quinta

Solução: três comandos, cada um com um papel

/context
/compact
/clear

/context mostra o uso atual do contexto em uma grade colorida, com sugestões de otimização. Ele aponta ferramentas pesadas em contexto, inchaço de memória e avisos de capacidade

É o diagnóstico. Comece por ele

/compact reduz o tamanho do histórico resumindo mensagens antigas e preservando o contexto importante

O erro comum deste passo: chamar o /compact numa conversa recém-aberta. Ele precisa de uma conversa existente com pelo menos duas trocas anteriores pra ter o que resumir

/clear reseta a conversa pra um contexto vazio, e os prompts seguintes começam sem histórico anterior

E aqui vai o alívio pra quem tem medo de apagar tudo: a conversa anterior continua salva em disco e pode ser retomada passando o session ID pra opção de resume

Como prevenir: trocar de tarefa é a hora de decidir entre compactar e limpar. Mesma tarefa, contexto grande demais? compacta. Assunto totalmente novo? limpa

Erro 6: contar com o desfazer pra tudo e pular o Git

Sintoma: uma mudança ruim passa, você corre pro rewind e ele simplesmente não traz aquilo de volta

Causa: entender errado o ALCANCE do checkpoint

Solução (e os limites dela): o Claude Code registra o estado do código antes de cada mudança e permite voltar atrás por um menu de rewind

O menu abre com /rewind ou apertando Esc duas vezes com o campo de prompt vazio

Caso o Esc duplo pareça não fazer nada: se houver texto no campo, ele apenas limpa o texto (e dá pra recuperar com a seta pra cima)

O menu lista cada prompt enviado na sessão e oferece ações distintas:

• restaurar código e conversa
• restaurar só a conversa, mantendo o código atual
• restaurar só o código, mantendo a conversa
• resumir a conversa a partir daquele ponto

Os checkpoints são salvos junto com a conversa, então o /rewind ainda funciona depois de retomar uma sessão

Agora os limites, que são o coração deste erro:

• só edições feitas pelas ferramentas de edição de arquivo do Claude entram no checkpoint
• mudanças por Bash ou processos externos (os rm, mv, cp da vida) NÃO podem ser desfeitas pelo rewind
• os checkpoints são apagados junto com as sessões depois de 30 dias

Deu pra sentir o tamanho do buraco? O comando que mais assusta é justamente o que o rewind não alcança

Como prevenir: rewind é conforto de sessão. Histórico permanente e colaboração continuam sendo Git, ponto

Erro 7: fazer toda busca e leitura na janela de contexto principal

Sintoma: uma investigação longa (ler dez arquivos pra entender um fluxo) consome a sessão inteira, e quando chega a hora de implementar não sobra espaço

Causa: não delegar

Solução: subagentes

Cada subagente roda na própria janela de contexto, com system prompt próprio, acesso específico a ferramentas e permissões independentes

A leitura pesada acontece lá, e o que volta pra sua sessão é o resultado

Mas calma, não é bala de prata

A janela do subagente começa ZERADA, sem a conversa do pai. O único conteúdo repassado é a string de prompt da ferramenta Agent

É como contratar alguém excelente que acabou de chegar na empresa: se você não contar o contexto, ele não adivinha

Como prevenir: escreva o pedido ao subagente como se ele não soubesse nada da conversa

Porque ele não sabe mesmo 🙂

Depois de corrigir os 7: quando vale automatizar com hooks

Ajustou os hábitos? Aí sim vale falar de automação

Hooks permitem automatizar ações determinísticas em torno das ferramentas do Claude Code

Eles podem ser configurados de dois jeitos:

• no settings.json, valendo pra sessão inteira, inclusive dentro de subagentes
• no frontmatter do subagente, valendo só enquanto ele está ativo

Um caso de uso concreto (com o limite junto, pra não criar expectativa errada): o hook PostToolUse roda DEPOIS que a ferramenta já executou

Então ele não consegue bloquear a operação

O que ele faz bem é ação de acabamento, tipo passar o caminho do arquivo editado pra um formatador

O recado é esse: hook resolve repetição mecânica

Ele não substitui plano, e não substitui revisão

Conclusão

Os sete erros no Claude Code que a gente passou aqui têm a mesma raiz: tratar a ferramenta como caixa de pedidos, quando ela é um ambiente CONFIGURÁVEL

Plan mode antes de editar, modo de permissão escolhido de propósito, CLAUDE.md no lugar do prompt repetido, auto memory pras preferências, /context com /compact e /clear, rewind com os limites claros e subagente pra investigação pesada

Próximo passo prático, hoje mesmo: roda /init no projeto atual e passa a próxima tarefa grande pelo plan mode antes de qualquer edição

Só isso já muda o resultado de forma absurda

E se quiser ir mais fundo, a Anthropic mantém uma página oficial de boas práticas do Claude Code na documentação do produto

até o próximo post! =)