A hierarquia da memória

Do mais amplo ao mais específico

As instruções de memória vivem em níveis, cada um com um alcance. O mais amplo e a política da organização, definida pela empresa e valida para todos na máquina; e usada por times que precisam padronizar regras de segurança ou conformidade. Vem depois o nível de usuário, que são as suas preferências pessoais valendo para todos os seus projetos, guardadas na sua pasta pessoal. Em seguida, o nível de projeto, o CLAUDE.md da raiz, compartilhado com o time. E, por fim, o mais específico, o arquivo local, com as suas preferências pessoais só daquele projeto.

A regra de ouro para escolher onde colocar algo e o alcance real da instrução. Uma preferência sua de estilo que vale para tudo que você faz mora no nível de usuário. Uma convencao do projeto que todo o time deve seguir mora no CLAUDE.md do projeto, para viajar pelo controle de versão. Uma configuração pessoal que só faz sentido para você naquele projeto, como um endereco de teste seu, mora no arquivo local. Colocar cada coisa no nível certo mantem o essencial visivel onde importa e evita poluir os outros contextos com detalhes que não lhes dizem respeito.

Os níveis se somam, não se sobrescrevem

Um ponto que costuma gerar dúvida: os níveis não competem, eles se somam. O Claude Code le todos os arquivos de memória aplicaveis e os junta no contexto, do mais amplo ao mais específico, com as instruções mais próximas do seu trabalho lidas por último. Ou seja, a preferência de usuário e a convencao do projeto convivem; não é uma ou outra. Isso é diferente de sobrescrever. Como todos entram juntos, o cuidado importante e evitar contradicoes: se dois níveis mandam coisas opostas para o mesmo caso, o agente pode escolher um deles de forma imprevisível.

Por isso, revisar a memória de vez em quando vale a pena. Instruções antigas que ninguém lembra, regras que mudaram e não foram atualizadas ou orientacoes que se contradizem entre os níveis atrapalham mais do que ajudam. Como tudo se soma, uma linha esquecida continua influenciando o agente em toda sessão. Um hábito saudavel e, quando o agente agir de um jeito estranho, checar se ha uma instrução velha ou conflitante em algum nível da memória puxando para o lado errado. A ferramenta ajuda a listar quais arquivos estão carregados.

Uma curiosidade útil: o Claude Code também le arquivos de memória em subpastas do projeto, mas só quando trabalha com arquivos daquela subpasta. Isso permite dar instruções específicas para uma parte do projeto sem poluir o resto. Em projetos grandes, com várias áreas, isso ajuda a manter cada canto com o seu contexto próprio, carregado só quando o agente entra ali. Você não precisa usar esse recurso no começo, mas e bom saber que a hierarquia tem também essa dimensão por pasta, além dos quatro níveis principais.

O arquivo local para o que é só seu

Vale um foco no nível mais pessoal ligado a um projeto, o arquivo local. Ele existe para preferências suas que só fazem sentido naquele projeto e que você não quer compartilhar com o time, como um endereco de ambiente de teste seu ou dados de exemplo que você prefere. Como e pessoal, ele deve entrar no gitignore, a lista de arquivos que não vao para o controle de versão, para não acabar no repositório do time. O comando de inicializacao, ao criar a versão pessoal, já cuida disso para você, adicionando o arquivo ao gitignore automaticamente.

Com a hierarquia clara, você já sabe onde guardar cada tipo de instrução para o agente chegar alinhado sem bagunca. A próxima aula muda o foco do onde para o como: escrever instruções que o Claude Code realmente segue. Porque colocar no lugar certo e metade do trabalho; a outra metade e escrever de um jeito claro, específico e enxuto, já que, como você viu, o CLAUDE.md e contexto, e a qualidade da escrita determina o quanto ele influencia o comportamento do agente.