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:

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.

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.

Artefato copiável: contexto em camadas com prazo e checagem

O exemplo abaixo funciona em qualquer repositório com Bash. Ele não substitui CI nem valida semântica de uma ADR; ele evita dois problemas baratos de detectar: referências locais quebradas e instruções temporárias que venceram.

Crie um CLAUDE.md enxuto na raiz:

# Working agreement

## Fonte de verdade

- Comandos de build, teste e lint: `package.json` e o CI; não invente comandos.
- Decisões de arquitetura: `docs/adr/`; se houver conflito, a ADR aceita mais recente vence.
- Regras locais carregam perto do código ou em `.claude/rules/` com `paths`.

## Segurança e autonomia

- Nunca execute deploy, migração, alteração de permissão ou escrita em produção sem confirmação explícita.
- Antes de alterar código: leia a regra mais próxima e identifique o comando de verificação.
- Ao concluir: mostre arquivos alterados, comandos executados, resultado e lacunas de verificação.

## Contexto temporário

- Toda exceção temporária usa `EXPIRES: YYYY-MM-DD`, dono e link para issue/ADR.
- Exemplo: `EXPIRES: 2026-10-01 | owner: @payments | ADR-042`.

Perto de um domínio, deixe a verdade local onde ela é acionada. Exemplo em .claude/rules/payments.md:

---
paths:
  - "apps/payments/**"
  - "packages/billing/**"
---

# Payments

- Contratos externos: `docs/adr/042-payment-idempotency.md`.
- Antes de editar fluxo de cobrança, rode o teste descrito em `packages/billing/package.json`.
- EXPIRES: 2026-10-01 | owner: @payments | Remover a compatibilidade v1 após a migração 842.

Por fim, adicione scripts/check-claude-context.sh, dê permissão de execução com chmod +x scripts/check-claude-context.sh e rode ./scripts/check-claude-context.sh no CI ou antes de revisar mudanças de contexto:

#!/usr/bin/env bash
set -euo pipefail

today="$(date +%F)"
status=0

while IFS= read -r -d '' file; do
  while IFS= read -r line; do
    path="${line#*@}"
    path="${path%%[[:space:]]*}"
    if [[ "$path" == /* || "$path" == ~/* ]] || [[ -z "$path" ]]; then
      continue
    fi
    if [[ ! -e "$(dirname "$file")/$path" ]]; then
      printf 'broken import: %s -> %s\n' "$file" "$path" >&2
      status=1
    fi
  done < <(grep -Eo '@[^`[:space:]]+' "$file" || true)

  while IFS= read -r expiry; do
    if [[ "$expiry" < "$today" ]]; then
      printf 'expired context: %s (%s)\n' "$file" "$expiry" >&2
      status=1
    fi
  done < <(grep -Eo 'EXPIRES: [0-9]{4}-[0-9]{2}-[0-9]{2}' "$file" | awk '{print $2}' || true)
done < <(find . -type f \( -name 'CLAUDE.md' -o -path './.claude/rules/*.md' \) -print0)

exit "$status"

O script deliberadamente falha ao encontrar uma exceção vencida. Não renove a data por reflexo: confirme se a exceção ainda existe, promova-a para uma decisão estável ou remova-a. Também vale adaptar o parser se seu projeto usa imports complexos; um check simples que deixa claro sua limitação é preferível a uma falsa garantia.

Decisões e trade-offs

Compactação merece um cuidado especial. Resumir uma sessão ajuda a continuar trabalhando, mas um resumo não é uma fonte de verdade. Após compactar, recupere o objetivo, os arquivos modificados, as decisões tomadas, os comandos já executados e o que ainda precisa de verificação. Reabra o diff e os testes relevantes em vez de assumir que o resumo preservou todas as exceções. Contexto comprimido é ótimo para continuidade; para fatos críticos, use artefatos versionados.

Ownership, segurança e verificação

Toda linha de contexto de alto impacto deveria responder quatro perguntas:

1. Quem pode alterá-la?
2. Que fonte a sustenta?
3. Em que escopo ela vale?
4. Como sabemos que ainda vale?

Uma prática simples é revisar contexto junto com mudanças de arquitetura, não como higiene anual. Se uma PR move o mecanismo de autenticação, ela deve atualizar a ADR e as regras de path relacionadas. Se a CI muda, atualize o comando canônico ou elimine a referência. Se uma exceção expira, atribua a decisão a alguém — não ao próximo agente que encontrar a data.

Para segurança, aplique o princípio do menor privilégio em três lugares: tools disponíveis, credenciais expostas e diretórios acessíveis. A permissão de leitura de um banco de analytics não justifica escrita em produção. Um MCP de tickets não justifica acesso a segredos. E instruções vindas de issues, logs ou conteúdo web devem ser tratadas como dados não confiáveis, não como novas políticas.

Para verificação, prefira evidência que outra pessoa consegue reproduzir: saída de teste, link de CI, diff, captura de tela, consulta read-only ou checklist assinado. "O agente disse que terminou" não é evidência. A documentação de boas práticas do Claude Code recomenda dar ao agente formas de validar o próprio trabalho e fornecer critérios claros de sucesso. Best practices (verificado em 12 de agosto de 2026).

Checklist operacional

• O CLAUDE.md raiz contém apenas fatos que quase toda sessão precisa?
• Cada comando citado existe hoje em package.json, Makefile, CI ou runbook?
• Toda regra local está no diretório ou paths mais específico possível?
• Procedimentos longos viraram skills ou runbooks em vez de texto carregado sempre?
• Memória automática foi revisada e não contém segredos, política ou decisões não confirmadas?
• Exceções temporárias têm EXPIRES, owner e referência rastreável?
• Ações irreversíveis são bloqueadas por permission/settings/hooks, não só por uma frase?
• MCPs e tools têm menor privilégio e uma finalidade clara?
• O fluxo pede uma verificação reproduzível antes de declarar sucesso?
• Há tarefas de avaliação que detectam regra errada, contexto faltante e instrução conflitante?

Conclusão: contexto bom sabe desaparecer

O objetivo não é transformar Claude Code em um funcionário que decorou a empresa. É criar um harness no qual ele encontra fatos atuais, recebe limites claros e deixa evidências antes de agir com mais autonomia.

Um CLAUDE.md excelente costuma ser menor do que o arquivo que ele substitui. Ele aponta para a verdade, não tenta carregá-la inteira. Memória ajuda a não reaprender o mesmo problema, mas é revisável. Regras locais aparecem no momento certo. Skills carregam playbooks. Hooks e permissões guardam limites reais. E compactação preserva continuidade sem virar prova.

Quando esse sistema funciona, o contexto não é um aterro de instruções. É uma cadeia de custódia: cada afirmação relevante tem escopo, dono, fonte e um caminho para ser apagada quando deixa de ser verdade.

Referências primárias

• Anthropic, How Claude remembers your project. Verificado em 12 de agosto de 2026.
• Anthropic, Claude Code settings. Verificado em 12 de agosto de 2026.
• Anthropic, Hooks reference. Verificado em 12 de agosto de 2026.
• Anthropic, Best practices for Claude Code. Verificado em 12 de agosto de 2026.
• Anthropic, Security. Verificado em 12 de agosto de 2026.
• Anthropic, MCP in Claude Code. Verificado em 12 de agosto de 2026.