Claude Code repete o mesmo erro depois de você corrigir: como quebrar o ciclo

Você corrige, ele diz que entendeu, agradece, promete não repetir

e duas mensagens depois o mesmo padrão errado tá lá de novo no arquivo

Se isso já te fez fechar o terminal com raiva, se liga: não é impressão sua e nem falta de jeito pra escrever prompt. Existem issues registradas no repositório oficial anthropics/claude-code descrevendo exatamente esse sintoma: a #47351 (Claude ignora instruções memorizadas e repete erros já corrigidos), a #37314 (falha em aplicar a própria memória, mesmos erros se repetem entre sessões) e a #43393 (feedback da auto memory não aplicado de forma confiável nas conversas seguintes)

Só que aqui vem a parte que muita gente pula: "ele repete erro" não é UM problema, são vários problemas diferentes com o mesmo sintoma

E cada um tem uma correção distinta. Sair mexendo em arquivo antes de saber qual é o seu caso é o jeito mais rápido de piorar (spoiler: inchar o CLAUDE.md é literalmente uma das causas)

Então bora fazer diagnóstico. Vou passar causa por causa, cada uma com sintoma, porquê e o que fazer. Nada aqui é sobre erro na hora de instalar, é sobre o agente já rodando e teimando

Causa 1: a correção só existe no chat

O sintoma é bem específico: dentro da mesma sessão ele acerta por um tempo, dez, quinze mensagens, e aí regride sozinho

Formação Recomendada

Formação Claude Code

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

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Na sessão seguinte então? Zero memória de que aquela conversa existiu

O motivo é mecânico, não é má vontade do modelo. O Claude Code gerencia o contexto automaticamente conforme se aproxima do limite: primeiro ele limpa saídas antigas de ferramentas, depois resume a conversa

E na hora de resumir, os seus pedidos e trechos-chave de código são preservados, mas instruções detalhadas dadas lá no começo da conversa PODEM se perder

Ou seja: aquela correção linda que você digitou na mensagem 3 não é uma lei, é um item de histórico. E histórico é justamente o que a compactação come

Como resolver:

A orientação da própria documentação é direta: regra que precisa persistir vai pro CLAUDE.md, não fica pendurada no histórico da conversa

Se a regra é "nunca use X nesse projeto", ela é permanente. Se é permanente, é arquivo

Como prevenir:

O comando /memory abre o arquivo direto no editor (e cria se ele ainda não existir), então não tem desculpa de "depois eu escrevo"

/memory

E se o projeto ainda nem tem CLAUDE.md, o /init lê a estrutura do projeto e gera um inicial com comandos de build, arquitetura e convenções. Roda o /init primeiro, refina com /memory depois

Causa 2: a regra está escrita, mas some depois do /compact

Esse caso é mais cruel, porque você fez a lição de casa

A instrução TÁ em arquivo. Você conferiu. E mesmo assim, no meio de uma sessão longa, o comportamento errado volta

O porquê: regras path-scoped e CLAUDE.md aninhados entram no histórico de mensagens quando o arquivo-gatilho é lido

E se elas estão no histórico de mensagens, adivinha? A compactação resume elas junto com o resto da conversa, igualzinho ao que acontece com a Causa 1

Elas voltam, sim, mas só na próxima vez que o Claude ler um arquivo que casa com o padrão. Até lá, é como se a regra não existisse

Como resolver:

O CLAUDE.md da raiz do projeto tem um comportamento diferente e é isso que salva você aqui: depois do /compact, ele é relido do disco e reinjetado na sessão

Então se uma regra PRECISA sobreviver, você tem dois caminhos: tirar o frontmatter paths dela, ou mover ela de vez pro CLAUDE.md da raiz

Como prevenir:

Na hora de escrever a regra, faça a pergunta antes: isso vale sempre ou vale só nesse diretório?

"Sempre" mora na raiz

"Só aqui" pode ser path-scoped, mas sabendo que ele some no resumo e volta na leitura

Causa 3: a regra nunca é carregada porque o gatilho não dispara

Aqui o sintoma é a regra path-scoped parecendo simplesmente ignorada em tarefas que, na sua cabeça, deveriam ativar ela

Acontece que o gatilho é bem literal: regra com o campo paths no frontmatter YAML só carrega quando o Claude lê um arquivo que casa com o glob

E o gatilho é a LEITURA do arquivo correspondente, não cada uso de ferramenta. Tarefa que não passou por aquele arquivo não acorda a regra

Já regra sem o campo paths carrega sempre e vale pra todos os arquivos

Como resolver:

Primeiro suspeito é o glob. Confere o padrão:

---
paths:
  - "src/**/*.{ts,tsx}"
---

Se o seu código não mora em src/, ou se a regra também precisa valer pro que está fora dali, o escopo tá errado. E se a regra é geral mesmo, o certo é remover o escopo em vez de tentar cobrir tudo com glob

Como prevenir:

Para de supor e vai olhar. O /memory lista os arquivos CLAUDE.md, CLAUDE.local.md e de rules que estão carregados na sessão atual

É a diferença entre "acho que ele tá lendo" e saber

Causa 4: o CLAUDE.md inchou e a regra se perdeu no ruído

Esse é o mais contraintuitivo de todos, porque o sintoma é: quanto MAIS instrução você acrescenta, PIOR fica a aderência

Parece injusto, né? haha

Mas a documentação registra o problema do arquivo longo demais: quando o CLAUDE.md fica grande, o Claude ignora parte dele, porque as regras importantes se perdem no meio do resto

A recomendação é mirar em menos de 200 linhas por arquivo, já que arquivos mais longos consomem mais contexto e reduzem a aderência às instruções

Então sim: aquele CLAUDE.md gigante que você foi engordando toda vez que ele errava é parte do motivo dele errar. É esse tipo de armadilha que faz o pessoal parar e questionar se o Claude Code compensa mesmo antes de olhar pro arquivo

Como resolver:

Podar sem dó

A correção sugerida é bem seca: se o Claude já acerta aquilo sem a instrução, apaga a regra ou converte ela em hook

Como prevenir:

Ter critério do que entra e do que fica de fora, decidido ANTES de escrever

Entra no arquivo:

• comandos que ele não teria como adivinhar
• regras de estilo diferentes do padrão
• instruções de teste
• etiqueta do repositório
• decisões de arquitetura
• peculiaridades do ambiente

Fica de fora:

• aquilo que ele descobre lendo o código
• convenções padrão da linguagem
• documentação extensa de API
• descrição arquivo a arquivo

E uma nota importante sobre a sintaxe @path, porque muita gente usa ela achando que tá economizando: ela importa arquivos adicionais de instrução e ajuda MUITO na organização, mas não reduz contexto

Os arquivos importados carregam no launch, todos eles. Quebrar um arquivo de 600 linhas em seis de 100 não deixa o contexto mais leve, só deixa você mais organizado =)

Causa 5: o contexto virou um empilhamento de tentativas falhas

Sabe aquele momento em que, a partir da terceira correção, cada resposta fica pior?

Ele começa a misturar padrões das tentativas anteriores, resolve com a abordagem que você já descartou duas vezes, inventa um híbrido tosco das duas

Isso tem nome na documentação: é o antipadrão de corrigir repetidamente. O Claude erra, você corrige, continua errado, você corrige de novo

E o contexto vai ficando poluído de tentativas que não deram certo

Tem um primo desse antipadrão que piora tudo: a sessão sem foco, quando tarefas não relacionadas convivem na mesma conversa e enchem o contexto de informação irrelevante

Como resolver:

A regra é bem objetiva: depois de duas correções sem sucesso, /clear e escreve um prompt inicial melhor, já incorporando o que você aprendeu nas tentativas

/clear

Dói jogar fora? Dói. Mas insistir na mesma conversa é alimentar o problema

E /clear também entre tarefas não relacionadas, não só quando dá ruim

Como prevenir:

Às vezes você não quer zerar, quer preservar o rumo

Pra isso o /compact aceita instrução em texto:

/compact focus on the auth bug fix

Assim você diz o que importa guardar em vez de deixar o resumo decidir sozinho. O comportamento da compactação também pode ser customizado por instruções no próprio CLAUDE.md

Causa 6: a instrução depende do modelo lembrar de segui-la

Esse é o caso do leitor que já fez tudo certo

A regra tá clara, tá curta, tá carregada (você conferiu no /memory), sobrevive à compactação

E ainda assim ele escorrega de vez em quando

A causa aqui é conceitual e é bom encarar: instrução em arquivo é ORIENTAÇÃO pro modelo, não garantia de execução. É como deixar um bilhete colado na parede, o cara lê, concorda, e ainda assim um dia passa batido

Como resolver:

Quando a regra não pode falhar, ela não pode ser bilhete, tem que ser tranca

É pra isso que servem os hooks: eles rodam em pontos específicos do ciclo de vida do Claude Code e dão controle determinístico, fazendo certas ações SEMPRE acontecerem em vez de depender do modelo decidir executar

Dois deles resolvem casos bem diferentes:

1. PreToolUse: roda depois que o Claude monta os parâmetros da ferramenta e antes da chamada ser processada, e pode bloquear. Sair com exit 2 barra a ação, e o texto escrito no stderr volta pro Claude como feedback pra ele se ajustar

# dentro do seu script de hook
echo "regra do projeto: nao edite esse arquivo direto" >&2
exit 2

O erro comum desse passo é escrever a mensagem no stdout: quem volta como feedback pro Claude é o stderr

2. PostToolUse: dispara com a ferramenta JÁ executada, então ele não bloqueia nada. Ainda assim o exit 2 serve como aviso, pra ele ver o stderr mesmo depois da ação ter acontecido

O erro comum aqui é esperar bloqueio de um PostToolUse. Não vem, o barco já saiu do porto

O exemplo da própria documentação é ótimo pra sentir a divisão: CLAUDE.md pras convenções do projeto, e um hook PostToolUse rodando o linter após cada edição, devolvendo o resultado como texto que o Claude lê

Como prevenir:

Dividir responsabilidades desde o começo

CLAUDE.md pro que é convenção e contexto

Hook pro que precisa acontecer sempre, sem depender de decisão

Onde escrever cada tipo de regra pra ela não sumir:

Juntando tudo, dá pra montar um mapa de decisão. Antes de escrever a regra, você responde "pra quem isso vale?" e o lugar aparece sozinho:

Detalhe que ajuda muito na organização: subdiretórios funcionam. Um .claude/rules/frontend/react.md é descoberto automaticamente, você não precisa registrar em lugar nenhum

E no Windows, ~/.claude resolve pra %USERPROFILE%\.claude, caso você fique procurando a pasta e não ache

E o que a auto memory cobre?

A auto memory é o outro mecanismo que atravessa sessões, e ela vem ligada por padrão

Cada projeto tem seu próprio diretório:

~/.claude/projects/<project>/memory/

Esse caminho é derivado do repositório git, o que tem uma consequência prática massa: todos os worktrees e subdiretórios do mesmo repo compartilham o mesmo diretório de memória

Se você quiser apontar pra outro lugar, dá pra trocar com a chave autoMemoryDirectory no settings.json, que é lida em qualquer escopo (user, project, local, policy ou --settings)

E se quiser desligar, tem três caminhos:

• o toggle dentro do /memory
• a chave "autoMemoryEnabled": false no settings do projeto
• a variável de ambiente CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

O /memory, aliás, é o painel de controle disso tudo: lista o que está carregado, abre o arquivo escolhido no editor, liga e desliga a auto memory e te dá acesso à pasta dela

Fecha a ideia assim: CLAUDE.md e auto memory são OS dois mecanismos que levam conhecimento de uma sessão pra outra, e ambos carregam no início de toda conversa. Se o conhecimento não está em um dos dois, ele não atravessa. Simples assim

Conclusão: o que fazer agora

Se você chegou aqui com um caso concreto na mão, a sequência é essa:

1. Roda /memory e olha o que está carregado DE VERDADE na sessão, em vez de supor
2. Decide se a regra ignorada está no lugar certo: raiz (sobrevive à compactação) contra path-scoped (some no resumo e volta na leitura do arquivo)
3. Poda o que virou ruído, mirando as menos de 200 linhas por arquivo
4. Promove a hook aquilo que não pode depender de decisão do modelo
5. E no calor do momento, aplica a regra das duas correções: falhou duas vezes, /clear e prompt novo

Agora o recado honesto, porque não adianta vender solução mágica: parte desse sintoma está registrada em issues no repositório oficial do Claude Code

Então se você arrumou o arquivo, conferiu o carregamento, podou o ruído, colocou hook no que importa e AINDA assim ele repete o mesmo erro, vale acompanhar por lá

Mas na prática, na maioria dos casos que eu vejo o pessoal relatando, é uma das causas acima e a correção é chata de tão simples: a regra estava no lugar errado

Me conta nos comentários qual era a sua, tenho curiosidade de saber qual causa é a campeã 😀

Até o próximo post!

Matheus Battisti