Claude Code memória: desligue e use AGENTS.md

Claude Code memória é um mecanismo da ferramenta de codificação agêntica da Anthropic que grava automaticamente anotações sobre seus projetos. Na prática, ele costuma acumular registros desatualizados que enganam o agente. Este artigo mostra por que desligar essa gravação automática e migrar o contexto para um AGENTS.md versionado tende a produzir resultados mais previsíveis.

Por que a memória automática do Claude Code atrapalha

Claude Code memória é um recurso da ferramenta de codificação agêntica da Anthropic que grava automaticamente anotações sobre seus projetos e as reinjeta em sessões futuras. O problema central é que essas anotações não passam por revisão, não têm dono e raramente são apagadas, então envelhecem em silêncio enquanto continuam orientando o modelo.

O desenvolvedor Theo, do canal t3.gg, auditou a própria máquina e encontrou 45 memórias acumuladas em um único clone do projeto T3 Code. Dessas, 26 nunca tinham sido lidas uma vez sequer. Em 355 sessões registradas, apenas 19 abriram algum arquivo de memória, enquanto 80 sessões gravaram ou editaram esses arquivos — uma proporção de escrita para leitura de aproximadamente 3 para 1.

Esse desequilíbrio explica o incômodo. O sistema produz mais conteúdo do que consome, e cada arquivo criado se torna uma fonte potencial de contexto obsoleto. Memória não é o mesmo que conhecimento durável do projeto.

O que a auditoria de memórias mostrou na prática

A auditoria expôs três categorias de degradação que se repetem em bases reais. A primeira é a redundância: cerca de 10 dos 45 arquivos descreviam regras que já existiam no AGENTS.md, lido por todo agente em toda sessão. A segunda é o design de funcionalidade já entregue, com números de pull request que perderam relevância. A terceira é o estado pontual, como esquemas de JSON que já mudaram.

Um exemplo concreto: uma memória registrava que a versão do GitHub CLI naquela máquina estava desatualizada e precisava de atualização. O desenvolvedor atualizou, o problema acabou, e a anotação continuou lá. Outra guardava um plano de comparação de duas abordagens discutidas três meses antes.

Nada disso é conhecimento durável. É o resíduo de uma conversa que já terminou, armazenado onde o modelo vai encontrá-lo de novo.

Por que o código é a fonte da verdade, não a memória

Memória é o lugar errado para registrar como o trabalho deve ser feito em uma base de código, porque o código já carrega essa informação e evolui junto com ela. Qualquer camada paralela de documentação tende a divergir, e o comentário desatualizado deixa de ser inofensivo: ele passa a dirigir pessoas e agentes na direção errada.

Dividir o conhecimento entre vários lugares cria problemas de cérebro dividido. Você muda uma regra no código, esquece de mudar no arquivo de contexto, e as duas versões coexistem. Modelos atuais leem um ou dois arquivos e entendem razoavelmente bem a estrutura e o estilo de uma base.

Um mapa de pastas com descrições curtas é fácil de manter pelo próprio agente. Acima disso, vale perguntar que evidência existe de que embeddings e sistemas de memória produzem respostas melhores — e, na prática, o desenvolvedor relata nunca ter visto uma avaliação que confirmasse isso.

Como estruturar um AGENTS.md que realmente funciona

Um AGENTS.md bem escrito descreve primeiro o que o produto é e como funciona, antes de listar regras. Theo abre o arquivo do T3 Code explicando que um servidor Node WebSocket encapsula CLIs de provedores para servir web, desktop e mobile. Essa frase curta alinha o modelo ao propósito do projeto.

A seção sobre o que torna o projeto especial existe para manter contribuidores e agentes na mesma direção. Inclui compromissos como manter o projeto aberto, o que já barrou sugestões de fechar parte do código. Uma nota sobre desempenho sem concessões reduziu regressões de carregamento de dados mais do que várias mudanças estruturais no próprio código.

Outras seções úteis incluem:

• Glossário, para fixar linguagem compartilhada e evitar termos inventados pelo modelo.
• Seção de superfícies, lembrando que toda mudança precisa funcionar em web, desktop e mobile.
• Verificação, restringindo checagens amplas de repositório a quando forem pedidas.
• Gosto pessoal, registrando preferências de estilo que o time já aplica em revisão.

A meta é simples: você deve se surpreender com a frequência com que o agente antecipa o que você queria, sem que você tenha dito tudo.

Elimine a classe de erro antes de escrever a regra

A ordem de valor proposta por Lauren, desenvolvedora do time do Cursor, organiza a solução em camadas. A primeira e mais valiosa é eliminar categoricamente a classe de problema por arquitetura ou escolha de estrutura de dados. A segunda é transformar a falha em regra de lint ou teste que a integração contínua captura.

Somente depois disso vêm skills e regras, tratadas como rede de segurança e não como plano principal. Um exemplo real: o T3 Code chegou a enviar dezenas de megabytes por WebSocket só para carregar uma thread. Depois da otimização, o consumo ficou consistentemente abaixo de 100 KB, e abaixo de 10 KB na maioria dos casos.

As regressões voltaram em dias. A solução foi adicionar um teste de integração contínua que reproduz threads reais, mede o tráfego e falha o pull request quando o valor passa de um teto 30% acima do patamar alcançado. Os agentes passaram a corrigir a regressão antes de avisar.

Onde a memória ainda faz sentido

Memória faz mais sentido em conversas do que em código. Em um chat, a ligação entre assuntos distantes pode ser legítima: uma pergunta sobre dor no ombro pode se conectar a uma compra de teclado semanas antes, sem caminho direto entre as duas.

Em uma base de código existe caminho direto. Você traça programaticamente o fluxo a partir de um botão clicado até tudo que ele toca. Por isso o mesmo mecanismo que ajuda em conversa atrapalha quando o objetivo é mudança de código precisa.

Existe também um efeito colateral conhecido: quando o modelo fica preso em um estado ruim, a memória pode reforçar esse estado em vez de permitir que a conversa se recupere. É aí que a resposta deixa de ser útil por estar saturada do seu próprio histórico.

O que fazer no lugar: passo a passo

Substituir a gravação automática por contexto versionado exige uma sequência curta e verificável. A ideia é mover o conhecimento durável para arquivos que passam por revisão e deixar o restante com o próprio agente, que já sabe navegar com ferramentas de linha de comando.

1. Desligue a gravação automática de memória nas suas máquinas e arquive o que já existe.
2. Mova o contexto durável para um AGENTS.md versionado, começando pelo que o produto é.
3. Transforme erros repetidos em regras de lint, testes ou limites de integração contínua.
4. Reserve skills e regras para processos que o código não consegue resolver.
5. Revise o arquivo quando a direção do projeto mudar, não a cada sessão.

A ordem importa. Cada camada só deve entrar quando a anterior não resolve.

Perguntas frequentes sobre Claude Code memória

• O que é Claude Code memória? É um recurso do Claude Code, a ferramenta de codificação agêntica da Anthropic, que grava anotações sobre seus projetos automaticamente e as reinjeta em sessões futuras. As anotações não passam por revisão e raramente são apagadas.

• Vale a pena desligar a memória do Claude Code? Na maioria dos casos de uso em código, sim. Uma auditoria encontrou 45 memórias em um projeto, das quais 26 nunca tinham sido lidas. O custo de manter contexto obsoleto supera o benefício na maior parte dos fluxos.

• Qual a diferença entre memória e AGENTS.md? A memória é gravada automaticamente e não tem dono. O AGENTS.md é um arquivo versionado, revisado e compartilhado por todo o time, então evolui junto com o código.

• O que colocar no AGENTS.md? Comece pelo que o produto é e como funciona, depois liste compromissos, superfícies afetadas, um glossário e o que o agente deve verificar. Regras de estilo entram quando já existem em revisão de código.

• Memória funciona bem em chat? Sim, em conversas a ligação entre assuntos distantes pode ser útil. Em código existe caminho direto entre causa e efeito, e o contexto acumulado só adiciona ruído.

• Como impedir regressões que o agente reintroduz? Elimine a classe de erro por arquitetura ou estrutura de dados. Se não for possível, transforme a falha em teste, regra de lint ou teto verificado na integração contínua.

• Skills resolvem esse problema? Não como plano principal. Skills servem para processos que o código, o lint e os testes não conseguem cobrir, como expor um servidor por Tailscale. Trate como rede de segurança.

• Preciso apagar as memórias antigas? Sim, arquive e remova. Uma memória que descreve um problema já resolvido continua orientando o modelo na direção errada.

• Como saber se o contexto está bem ajustado? Quando você pede uma tarefa pequena e o agente antecipa efeitos colaterais que você também queria corrigir. Se isso não acontece com frequência, o alinhamento ainda não está bom.

Como times brasileiros podem aplicar isso

Quem acompanha conteúdo de desenvolvimento no Brasil encontra versões desse debate no Crazystack Typescript, comunidade mantida por Gustavo Dev Doido. A ideia de eliminar classes de erro por arquitetura, que o vídeo apresenta como ordem de valor, é a mesma que sustenta stacks com tipos compartilhados entre back-end e front-end.

Se você quer aprofundar, o Bootcamp do Dev Doido trabalha essas decisões de arquitetura aplicadas. O ponto central para times brasileiros é o mesmo: contexto de projeto precisa ser versionado e revisado, não gravado automaticamente por uma ferramenta.

Trocar memória automática por um AGENTS.md enxuto e testes de integração contínua é uma mudança barata. Ferramentas mudam, o repositório continua sendo a fonte da verdade.

Transforme seus vídeos em artigos com o Skala Blog

Assim como o vídeo que originou este texto, muita gente tem conhecimento valioso gravado em vídeos do YouTube: explicações técnicas, opiniões, entrevistas e aulas que ficam presas no formato audiovisual. Esse acervo poderia virar texto pesquisável, com estrutura e fontes verificáveis.

O Skala Blog faz exatamente essa ponte: você cola a URL do vídeo, o sistema transcreve e gera um artigo completo para revisão. É a mesma lógica do AGENTS.md — pegar o que já existe e organizar de um jeito que outras pessoas consigam usar.

Source video