Context Engineering no Claude Code: CLAUDE.md, memória e contexto que não apodrece

---

TL;DR

• Contexto confiável é pequeno, local e atribuível.
• Separe instruções, memória, ADRs e runbooks.
• Remova regras antigas antes que elas contaminem decisões.

Exemplo concreto: uma regra para pagamentos deve viver perto do módulo de pagamentos, não em um manual global de centenas de linhas.

O primeiro sinal de que o contexto do seu agente apodreceu não é uma resposta ruim. É quando ele responde com confiança usando uma regra que o time já abandonou, roda o comando de teste errado ou trata uma decisão local como lei do repositório inteiro.

Quase sempre a reação é acrescentar mais texto ao CLAUDE.md: mais arquitetura, mais exceções, mais comandos, mais "nunca faça X". Isso parece prudente, mas cria o problema que tenta resolver. Cada sessão passa a começar com uma enciclopédia parcialmente verdadeira; a instrução crítica compete com detalhes históricos, e ninguém sabe qual trecho ainda merece confiança.

Minha tese é simples: context engineering no Claude Code é gerir conhecimento por origem, escopo, tempo de vida e evidência — não maximizar o número de tokens de contexto. Um bom sistema dá ao agente o bastante para tomar a próxima decisão com segurança, carrega o resto just-in-time e torna cada afirmação importante verificável ou removível.

Isso é menos glamouroso do que "um agente que conhece todo o monorepo". Também funciona melhor.

O que context engineering é — e o que não é

Context engineering é o desenho deliberado de como um agente recebe, encontra, atualiza e descarta informação durante o trabalho. No Claude Code, isso inclui CLAUDE.md, regras em .claude/rules/, memória automática, skills, arquivos do repositório, ferramentas, permissões, sessão atual e resultados de verificação.

Não é sinônimo de prompt longo. Nem é uma base de conhecimento jogada inteira no início da conversa. Um prompt com 800 linhas pode conter informação; dificilmente contém prioridade, validade ou dono.

Também não é substituir documentação de produto, ADR, runbook, testes ou controle de acesso por instruções em Markdown. Esses artefatos têm papéis distintos:

Fonte	Pergunta que responde	Dono	Deve guiar o agente?
Código e testes	O que o sistema faz agora?	Time que mantém o código	Sim, como evidência principal
ADR ou RFC aceita	Por que uma decisão existe?	Dono técnico da decisão	Sim, quando a decisão é aplicável
Runbook	Como operar ou recuperar com segurança?	Operações/SRE	Sim, com aprovação onde houver impacto
CLAUDE.md	Como trabalhar consistentemente aqui?	Time do repositório	Sim, como contrato operacional
Memória automática	O que foi aprendido em sessões anteriores?	Claude, revisado por humanos	Sim, como pista; não como autoridade final
Chat atual	O que esta tarefa pede agora?	Pessoa solicitante	Sim, dentro do escopo declarado

Um workflow simples ainda é melhor quando a tarefa é previsível: gerar tipos, rodar uma migração revisada, publicar um pacote por pipeline ou formatar um diretório. Aí um script versionado com entradas e saídas claras é mais barato de operar e auditar. Use um agente quando ele precisa investigar, escolher a sequência de ferramentas ou lidar com ambiguidade. E, mesmo então, use scripts para as partes determinísticas.

Na documentação atual, a Anthropic separa dois mecanismos persistentes: CLAUDE.md, escrito por pessoas para instruções, e auto memory, em que o Claude registra aprendizados. Os dois entram como contexto; nenhum deles é uma política técnica que o cliente obrigatoriamente fará cumprir. Para bloquear uma ação, a própria documentação recomenda uma regra de permissão ou um hook PreToolUse. Essa fronteira é a primeira defesa contra contexto aspiracional: "não faça deploy" em Markdown não vale tanto quanto uma permissão que nega o comando. How Claude remembers your project (verificado em 12 de agosto de 2026).

As quatro falhas que fazem o contexto morrer

Antes de desenhar camadas, vale reconhecer os padrões que tornam um CLAUDE.md caro e pouco confiável.

1. O manual de onboarding disfarçado de instrução

O arquivo começa pequeno: comandos de teste, convenções de import e um aviso sobre produção. Seis meses depois contém a história do sistema, cada pacote do monorepo, uma lista de incidentes e um tutorial de deploy. O agente recebe tudo em toda sessão, inclusive quando só precisa alterar um componente.

O dano não é apenas custo. Instruções longas diminuem a chance de a regra certa ser percebida e seguida. A documentação do Claude Code recomenda arquivos específicos, concisos e estruturados, e aponta cerca de 200 linhas como alvo para um CLAUDE.md; regras que só importam para um caminho devem ser carregadas condicionalmente. Memory: write effective instructions (verificado em 12 de agosto de 2026).

Correção: o CLAUDE.md raiz deve ser um índice operacional: comandos verdadeiros, limites não negociáveis, mapa mínimo e links para a fonte canônica. Processo longo vira skill. Regra de domínio vira regra com escopo de path. História vira ADR, runbook ou documento de referência aberto só quando necessário.

2. Uma fonte de verdade que não é verdadeira

"Use yarn test" permanece depois da migração para pnpm. "Toda API fica em src/api" sobrevive à extração de serviços. A instrução foi correta uma vez; hoje é uma alucinação versionada no Git.

Contexto obsoleto é perigoso porque parece mais autoritativo que o código. O agente tende a obedecer à frase explícita antes de descobrir que ela conflita com package.json, CI ou testes recentes.

Correção: cada instrução operacional deve ter uma evidência próxima: o comando vem de package.json, a decisão vem de uma ADR aceita, o procedimento vem do runbook. Quando não houver como verificar automaticamente, declare dono e data de revisão. "Billing: @payments-team; revisar até 2026-11-01" é muito melhor que uma regra eterna sem responsável.

3. Escopo global para uma verdade local

Uma convenção de iOS vaza para o backend. Requisitos PCI do billing aparecem quando alguém corrige CSS. Um pacote legado impõe uma exceção a todos os pacotes novos. O resultado é ruído e, pior, instruções contraditórias.

O Claude Code lê arquivos CLAUDE.md na hierarquia acima do diretório de trabalho e adiciona contexto de subdiretórios quando seus arquivos são acessados. Regras em .claude/rules/ podem ter paths para só entrar quando o agente trabalha em padrões compatíveis. Isso permite proximidade sem transformar o root em depósito global. How CLAUDE.md files load e path-specific rules (verificados em 12 de agosto de 2026).

Correção: escreva a regra no menor escopo que ainda a torna verdadeira. Use o root para invariantes do repositório; diretórios para contratos locais; paths para tecnologia; skills para procedimento sob demanda.

4. Memória tratada como diário ou banco de política

Memória automática pode registrar comandos, padrões de debugging e preferências descobertas. Isso é útil porque evita repetir correções. Não é o lugar ideal para segredo, aprovação de arquitetura, regra de segurança ou uma exceção que precisa de revisão formal.

Ela também pode envelhecer. A documentação descreve a memória automática como notas por projeto, compartilhadas entre worktrees do mesmo repositório, com um MEMORY.md conciso e arquivos de tópico. Essa característica é valiosa, mas pede auditoria: uma descoberta em uma branch não se torna verdade universal só porque foi lembrada. Auto memory (verificado em 12 de agosto de 2026).

Correção: trate memória como cache de aprendizado. Promova uma informação para CLAUDE.md, ADR ou runbook somente depois de confirmar a fonte e o dono. Remova notas que deixam de ajudar uma próxima sessão. Nunca use memória como cofre de credenciais ou como justificativa para burlar revisão.

O harness: contexto é só uma camada do sistema

Um agente confiável não é definido por suas instruções. Ele é o conjunto de modelo, contexto, ferramentas, permissões, ambiente, verificação e observabilidade. Chamar tudo de "prompt" esconde decisões fundamentais.

Camada	Responsabilidade	Falha típica	Controle útil
Contexto	Explicar objetivo, limites e fatos estáveis	Regra velha ou genérica	Escopo, validade, link para fonte
Tools	Ler, editar, buscar e executar	Ação fora do necessário	Allowlist, menor privilégio
Permissões	Decidir o que pode acontecer	Confundir instrução com bloqueio	deny, aprovação e modo de plano
Ambiente	Isolar dados e dependências	Segredos e produção acessíveis	Sandbox, credenciais temporárias, read-only
Verificação	Provar a mudança	Saída plausível sem evidência	Teste, lint, diff, screenshot, log
Observabilidade	Reconstruir o que ocorreu	Ninguém sabe por que agiu	Logs de comando, PR, CI, telemetria aprovada

O ponto decisivo: CLAUDE.md molda comportamento; settings e hooks podem impor limites. A documentação separa expressamente os dois, e recomenda revisar comandos sugeridos, mudanças em arquivos críticos e servidores MCP antes de confiar neles. Claude Code security (verificado em 12 de agosto de 2026).

Isso muda como escrever instruções. Não escreva "nunca revele segredos" e conclua que o problema acabou. Tire segredos do ambiente quando possível, limite ferramentas e rede, negue caminhos sensíveis, use credenciais de menor privilégio e peça confirmação humana antes de efeitos externos. Contexto é orientação; controles são arquitetura.

Uma escada incremental para contexto saudável

Não comece com memória automática, hooks, MCP e três subagents. Comece pelo menor mecanismo que torna o trabalho repetível e seguro.

1. Trabalho: descreva a decisão, não a persona

Ruim: "você é um engenheiro sênior que conhece nossa plataforma".

Bom: "ao alterar apps/api/**, preserve o contrato OpenAPI, execute os testes do pacote e pare para confirmação antes de tocar em migrações".

A segunda frase define gatilho, superfície, verificação e fronteira de autonomia. É possível contestá-la; a primeira só soa importante.

2. Contrato: ponha o universal no CLAUDE.md raiz

O root merece regras que se aplicam de verdade a quase toda tarefa: como achar comandos, o que é proibido, quando parar e o que constitui conclusão. Use links ou imports para fontes que realmente precisam ser lidas sempre; imports também carregam conteúdo no início, portanto não são uma desculpa para uma árvore infinita.

3. Skill: mova playbooks que só algumas tarefas usam

Uma investigação de incidente, uma revisão de acessibilidade ou um release têm passos e evidências próprios. Isso não pertence a toda sessão. Uma skill entrega o processo quando solicitada ou quando relevante, deixando a base leve. A regra prática é: se a instrução começa com "quando você estiver fazendo X", considere uma skill; se começa com "em todo arquivo Y", considere regra de path.

4. Agent: isole papel e memória quando o trabalho justifica

Subagent vale a pena quando a pesquisa é grande, o resultado pode ser resumido ou as permissões precisam ser diferentes. Dê a ele uma missão estreita, tools mínimas e uma saída que declare evidências, incertezas e próximos passos. Não crie um subagent só para esconder que o contexto principal está desorganizado.

5. Hooks/MCP: integre e imponha apenas o que é necessário

Hooks são bons para bloqueios determinísticos e coleta de evidência. MCP é útil quando uma fonte externa melhora materialmente a decisão. Ambos ampliam superfície de ataque: conteúdo remoto pode tentar orientar o agente, e uma tool pode transformar leitura em efeito externo. Mantenha servidores confiáveis, escopo read-only quando possível e aprovação para operações de escrita. A Anthropic reforça que servidores MCP de terceiros não são auditados por ela. MCP in Claude Code e Security (verificados em 12 de agosto de 2026).

6. Autonomia: escolha reversibilidade antes de velocidade

Uma edição local com testes é reversível. Um deploy, uma alteração de permissão ou uma migração de dados pode não ser. Para a segunda classe, plano antes da execução, checkpoint humano e trilha de auditoria são parte da definição de pronto. A melhor autonomia é aquela que para em limites previsíveis.

7. Evals: teste o contexto como produto

Monte tarefas representativas: corrigir um endpoint, alterar uma tela, investigar uma falha de CI, tocar um diretório legado. Para cada uma, registre se o agente carregou a regra certa, se buscou a fonte de verdade, se tentou ação proibida, se executou a verificação e se declarou o que não verificou. Uma regra que parece boa em uma conversa e falha em três cenários reais não é uma boa regra.