Por que meus agentes leem um vault, e não um CLAUDE.md gigante

Todo arquivo de instruções para agente começa pequeno e honesto. Umas regras de estilo, o comando de build, onde ficam os testes. Alguns meses depois ele não cabe mais numa tela, ninguém lembra por que metade das regras existe, e você paga esse arquivo inteiro em tokens toda vez que abre uma sessão — inclusive para perguntar que horas são.

O problema não é o tamanho. É que dois tipos muito diferentes de informação foram parar no mesmo lugar.

Duas coisas que não são a mesma coisa

Parte do que está ali configura o agente: use worktree antes de mexer no código, nunca instale nada sem perguntar, rode o lint antes de abrir PR. É operacional, é curto, e precisa estar em memória o tempo todo porque governa toda ação.

A outra parte decide pelo projeto: por que o serviço de pagamento fala com o de pedidos por evento e não por chamada direta, por que aquele campo é nullable, qual alternativa foi descartada em 2025 e por quê. É conhecimento denso, cresce sem parar, e você precisa dele em talvez uma sessão a cada dez.

Enfiar os dois no mesmo arquivo faz você pagar o preço do segundo com a frequência do primeiro.

A separação

O que eu faço hoje é manter dois lugares com autoridades diferentes:

• O arquivo de configuração (CLAUDE.md) ficou sendo um roteador. Regras sempre-ativas, mapa de onde as coisas estão, e ponteiros. Ele não explica nada — ele diz onde a explicação mora.
• O vault virou a autoridade canônica. ADRs, especificações, decisões, lições. O agente lê sob demanda, quando o trabalho encosta naquilo.

A regra que faz isso funcionar é chata e essencial: o local refina, nunca contradiz. Quando um CLAUDE.md de projeto e o vault discordam, o vault ganha. Sem essa regra você não tem duas camadas, tem duas fontes de verdade — que é o mesmo que não ter nenhuma.

O que mudou na prática

O custo de abrir uma sessão virou constante, em vez de crescer junto com o projeto. Quando o agente precisa de contexto profundo, ele busca — e busca a versão certa, porque tem um lugar só onde aquilo mora.

O ganho menos óbvio veio depois: quando escrever uma decisão passou a ter um endereço fixo, elas passaram a ser escritas. Antes, decisão de arquitetura ou virava comentário no código, ou sumia no histórico do chat.

Onde isso quebra

Não é de graça. A camada indireta significa que o agente às vezes não sabe que precisa buscar — ele responde com o que tem em memória, com confiança, sem perceber que existia um ADR contradizendo. A mitigação é ter no roteador uma ordem explícita de resolução, dizendo onde procurar antes de responder.

E vault desatualizado é pior que vault inexistente: um arquivo errado no lugar canônico é lido como verdade. Se você não tiver disciplina de atualizar no fim da tarefa, a separação trabalha contra você.