Por que separo instruções do conhecimento do projeto
Separar as instruções do agente do conhecimento do projeto evita pagar o mesmo custo em toda sessão.
Todo arquivo de instruções para um agente de IA (programa que executa tarefas) começa pequeno. Tem algumas regras de estilo, o comando para preparar o programa para rodar e o lugar onde ficam os testes. Alguns meses depois, já não cabe em uma tela. Ninguém lembra por que metade das regras existe. E você paga por todos aqueles tokens (unidades de texto lidas pelo modelo) em cada sessão. Até quando só quer perguntar as horas.
O tamanho não é o que me incomoda. O problema é juntar dois tipos muito diferentes de informação no mesmo lugar.
Duas coisas diferentes
Uma parte configura o agente: use um worktree (cópia separada dos arquivos do projeto) antes de mexer no código. Não instale nada sem perguntar. Rode o lint (checagem automática do código) antes de abrir um PR (pedido para revisar e incluir mudanças). São regras práticas, curtas, e precisam ficar na memória porque orientam toda ação.
A outra parte registra decisões do projeto. Por que o serviço de pagamentos avisa o de pedidos por um evento? É uma mensagem de que algo aconteceu. Assim, ele evita fazer uma chamada direta. Por que aquele campo pode ficar vazio? No código, o campo é nullable. Qual alternativa foi descartada em 2025, e por quê? Esse conhecimento é detalhado e cresce sem parar. Você talvez precise dele em uma sessão a cada dez.
Colocar os dois tipos no mesmo arquivo faz você pagar o custo do segundo com a frequência do primeiro.
A separação
Hoje mantenho dois lugares, com funções diferentes:
- O arquivo de configuração (
CLAUDE.md) virou um roteador: um guia que mostra ao agente onde procurar. Ele contém regras sempre ativas, um mapa dos arquivos e indicações. Não explica o assunto. Mostra onde encontrar a explicação. - O vault (repositório de documentos do projeto) virou a fonte oficial. Ele guarda ADRs (registros das decisões de arquitetura), além de especificações, decisões e lições. O agente consulta esses documentos quando o trabalho chega àquela parte do projeto.
A regra que faz isso funcionar é simples: as instruções locais podem acrescentar
detalhes, mas nunca contradizer o vault. Se um CLAUDE.md do projeto e o vault
discordam, vale o vault. Sem essa regra, você tem duas fontes que dizem ser oficiais. Na
prática, não tem nenhuma.
O que mudou na prática
O custo de iniciar uma sessão ficou constante, em vez de crescer junto com o projeto. Quando o agente precisa de informações detalhadas, ele busca a versão certa. Existe um lugar único para cada assunto.
O ganho menos óbvio veio depois. Quando as decisões passaram a ter um endereço fixo, elas começaram a ser registradas. Antes, uma decisão sobre a estrutura do sistema virava comentário no código ou desaparecia no histórico da conversa.
Onde isso falha
A separação cria uma etapa a mais. Às vezes, o agente não percebe que precisa consultar o vault. Ele responde com o que já sabe, com confiança, sem notar que existe uma decisão registrada que diz outra coisa. Para evitar isso, o roteador precisa dizer claramente onde procurar antes de responder.
Um vault desatualizado é pior que não ter vault. O agente pode ler um arquivo errado no lugar oficial e tratá-lo como verdade. Se você não atualizar os registros ao terminar o trabalho, essa separação acaba atrapalhando.