Context Engineering no Claude Code: CLAUDE.md, memória e contexto que não apodrece
- 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.
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.
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.