Como fazer o Claude Code aprender com os erros: CLAUDE.md, arquivo de aprendizados e verificação

Não por conta própria. A documentação oficial explica que cada sessão começa com uma janela de contexto nova. O conhecimento passa de uma sessão para outra por dois caminhos: arquivos CLAUDE.md que você escreve e a memória automática, com notas que o próprio Claude registra.

É um arquivo de instruções que o Claude Code carrega no início de cada conversa. Nele ficam padrões de código, comandos do projeto, decisões e regras de trabalho. Quanto mais específico e curto, mais fácil de a ferramenta seguir em vez de ignorar o texto.

É o recurso em que o Claude registra notas sozinho, com base nas suas correções e preferências. A documentação informa que ela vem ativada por padrão em sessões locais. Você pode abrir o comando /memory para ver, editar ou desligar o que foi guardado.

O CLAUDE.md é escrito por você e funciona como regra permanente. A memória automática é escrita pelo Claude, a partir do que ele aprende no uso. Os dois são carregados no início da conversa e se complementam, mas só o primeiro tem sua autoria direta.

É um arquivo, criado por você, onde o agente anota o que deu errado e o que funcionou ao final de cada sessão. Quando o mesmo erro se repete, a regra correspondente sobe para o CLAUDE.md. O nome learnings.md é uma convenção de criadores, não um recurso oficial.

Escreva no CLAUDE.md uma instrução curta: no início de cada sessão, leia o arquivo de aprendizados. A documentação permite importar outros arquivos no CLAUDE.md com a sintaxe de arroba. Teste na prática, porque o modelo pode deixar de seguir uma instrução vaga.

Inclua no arquivo de aprendizados a regra de gravar um resumo ao encerrar o trabalho: o que foi feito, o que falhou e o que mudar. Como o modelo não sabe quando você vai sair, peça o registro ao fim de cada tarefa concluída, não só no fim do dia.

São as condições que o trabalho precisa cumprir para ser considerado pronto. Em um site, por exemplo: todos os botões funcionam, nenhum elemento fica sobre outro, nenhuma imagem cobre texto. Escritos antes da execução, evitam discussões sobre o que significa estar certo.

Em um arquivo próprio, referenciado pelo CLAUDE.md. Assim, o protocolo fica organizado e pode ser reaproveitado entre projetos, embora o arquivo importado carregue junto com o principal. Basta apontar o caminho com a menção por arroba, ou copiar o caminho relativo pelo editor, como o VS Code.

Arquivos acima de 200 linhas consomem mais contexto e reduzem a aderência, segundo a documentação, que recomenda instruções concretas e enxutas e indica as skills para procedimentos longos, já que o corpo da skill só carrega quando ela é usada.

Quando você cola o mesmo passo a passo no chat toda hora, ou quando um trecho do CLAUDE.md virou procedimento em vez de fato. A documentação sugere criar uma skill nesses casos, pois o conteúdo só custa contexto quando for chamado.

Peça um teste: uma tarefa em que a regra faz diferença, e confira o resultado. Se a instrução for ignorada, reduza o arquivo, torne a regra mais concreta e remova contradições. A documentação tem uma seção de solução de problemas sobre isso.

O CLAUDE.md da raiz do projeto é recarregado depois da compactação, segundo a documentação. Instruções dadas só na conversa podem se perder. Por isso, regras importantes devem ir para o arquivo, e não ficar apenas no que você digitou no chat.

A documentação diz que o Claude Code pode ler um AGENTS.md do repositório no lugar do CLAUDE.md. Isso ajuda quem usa mais de um agente de programação no mesmo projeto, sem manter dois arquivos com as mesmas regras e correr o risco de divergirem.

Sim. O comando /memory abre o que está guardado e permite editar ou apagar notas. Vale revisar de tempos em tempos: uma nota errada ou antiga influencia as respostas seguintes. Anote também decisões do projeto em arquivo versionado, para a equipe ver.

Com cuidado. Um arquivo global vale para todos os seus projetos e pode mudar o comportamento do agente em tudo. Teste primeiro em um projeto isolado, leia cada regra e remova o que não faz sentido para o seu caso antes de levar para o nível global.

Não. Memória e verificação diminuem a repetição de erros conhecidos, mas não eliminam falhas novas. O agente continua precisando de revisão humana, principalmente em código que vai para produção. Registre o erro, ajuste a regra e confira o próximo resultado.