As novas regras de engenharia de contexto para os modelos da geração Claude 5

O orçamento de atenção

O material anterior da Anthropic já apontava a raiz do problema. Modelos de linguagem operam com um orçamento de atenção finito, e cada novo token consome uma parte dele.

Por isso, boa engenharia de contexto significa encontrar o menor conjunto possível de tokens de alto sinal que maximize a chance do resultado desejado. Em outras palavras, mais instrução não significa mais qualidade.

Esse limite tem origem na arquitetura transformer. Nela, cada token atende a todos os demais, o que gera relações par a par que crescem de forma quadrática conforme o contexto aumenta.

Ou seja, cada instrução adicional tem custo. Ela compete por atenção com todas as outras, inclusive com o pedido real do usuário.

Da regra ao julgamento

A primeira mudança abandona regras absolutas em favor do julgamento do modelo. O prompt de sistema antigo mandava o Claude não escrever comentários por padrão, nunca produzir blocos de comentário multilinha e evitar documentos de planejamento não solicitados.

Essa instrução fazia sentido para modelos anteriores. No entanto, ela era errada para uma parte relevante dos pedidos, como código complexo que exige explicação ou usuários com padrões próprios de documentação.

A formulação nova inverte a lógica.

Em vez de proibir, ela pede que o código novo se pareça com o código ao redor. Isso inclui a densidade de comentários, a nomenclatura e o idioma da base.

A regra antiga codificava uma decisão, enquanto a nova codifica um critério. Assim, a decisão fica com o modelo, que tem acesso ao repositório e a um contexto que você não tinha ao escrever a regra.

Na prática, a engenharia de contexto agora prefere instruções relacionais a instruções absolutas. Reserve palavras como sempre e nunca para os poucos casos em que a exceção realmente não existe.

Do exemplo ao design de interface

Na engenharia de contexto, a segunda mudança é talvez a mais contraintuitiva para quem escreve ferramentas. Por muito tempo, a regra número um do uso de tools foi fornecer exemplos de chamada.

Com a geração atual, porém, os exemplos passaram a restringir o espaço de exploração do modelo. Eles ancoram o comportamento nos padrões demonstrados.

A recomendação substituta é investir no desenho da própria ferramenta. Então, a pergunta deixa de ser como demonstrar o uso e passa a ser quais parâmetros existem e quão expressivos eles são.

O exemplo citado é a ferramenta de Todo. Declarar o campo de status como uma enumeração entre pending, in_progress e completed já comunica a semântica esperada sem nenhum exemplo de uso.

Um schema ilustrativo nesse estilo ficaria assim:

{
  "name": "todo_write",
  "description": "Tracks task progress. Keep only one item in_progress at a time.",
  "input_schema": {
    "type": "object",
    "properties": {
      "content": { "type": "string" },
      "status": {
        "type": "string",
        "enum": ["pending", "in_progress", "completed"]
      }
    },
    "required": ["content", "status"]
  }
}

Repare que a instrução de manter apenas um item em progresso define o comportamento em uma linha, dentro da própria descrição. Dessa forma, nomes de parâmetros, tipos, enumerações e restrições de schema funcionam como documentação executável e carregam mais sinal por token do que qualquer exemplo narrado.

Da carga inicial à divulgação progressiva

A terceira mudança trata de quando o contexto entra, e não de quanto contexto existe. Como o Claude Code nasceu focado em programação, o prompt de sistema carregava instruções detalhadas sobre revisão de código e verificação.

Essas informações raramente eram necessárias, mas, quando eram, se tornavam críticas. A solução foi mover verificação e revisão de código para skills próprias, que o Claude aciona apenas quando a tarefa exige.

Esse é o princípio da divulgação progressiva, ou progressive disclosure, um dos pilares da engenharia de contexto atual. A ideia é carregar a informação certa no momento certo, em vez de antecipar tudo.

O mecanismo vai além das skills. Parte das ferramentas do Claude Code usa carregamento diferido, e o agente precisa buscar a definição completa via ToolSearch antes de usá-la.

Com isso, o produto oferece muito mais ferramentas sem que todas ocupem contexto o tempo inteiro. O mesmo raciocínio derruba o mito de que CLAUDE.md e SKILL.md precisam concentrar tudo o que talvez seja necessário.

A recomendação é o oposto: manter uma árvore de arquivos que o modelo carrega quando fizer sentido. Vale, contudo, reconhecer o custo, porque explorar em tempo de execução é mais lento e exige uma organização de arquivos clara.

Da repetição às descrições simples

A quarta mudança na engenharia de contexto decorre diretamente da evolução dos modelos. Versões anteriores às vezes precisavam de instruções repetidas e davam mais peso ao fim da janela de contexto do que ao início.

Isso levava a uma duplicação estrutural, com referências a ferramentas no prompt de sistema e instruções equivalentes na descrição da tool. Agora, a orientação é simples: instruções sobre como usar uma ferramenta pertencem à descrição da ferramenta.

O benefício vai além da economia de tokens. Na verdade, eliminar a duplicação remove uma fonte crônica de contradição, já que duas cópias da mesma regra tendem a divergir com o tempo.

Da memória manual à memória automática

A quinta mudança altera o modelo mental sobre persistência entre sessões. Antes, a prática recomendada era usar um atalho de tecla para gravar informações no CLAUDE.md, transformando o arquivo em memória de longo prazo.

Agora o Claude salva automaticamente as memórias relevantes para o trabalho e para o usuário. Por consequência, o CLAUDE.md volta a ser um documento de projeto, curado e estável, em vez de um log que cresce sem revisão.

De especificações simples a referências ricas

A sexta mudança amplia o que a engenharia de contexto aceita como especificação. Historicamente, o modo de planejamento dependia de arquivos markdown com planos, e a boa prática era manter specs versionadas no repositório.

O modelo atual lida com referências bem mais complexas. Um artifact HTML gerado pelo próprio produto, por exemplo, funciona como referência com fidelidade maior do que uma descrição textual.

Referências também podem ser código. Uma suíte de testes detalhada é uma especificação executável, assim como uma função de outra base que você deseja portar.

Rubricas formam uma terceira categoria.

Elas permitem que o Claude verifique se o resultado atende ao seu critério de qualidade, como um bom design de API. Para isso, fluxos dinâmicos criam agentes verificadores que operam sobre a rubrica.

Prompt de sistema na engenharia de contexto

O prompt de sistema está atrelado ao produto. Ele informa ao Claude em qual produto está operando e qual é a natureza do trabalho.

Quem usa o Claude Code dificilmente vai mexer nessa camada. Por outro lado, quem constrói o próprio harness de agente deve concentrar o esforço exatamente aqui.

CLAUDE.md

A orientação é manter o arquivo leve, com uma descrição breve do propósito do repositório.

A maior parte dos tokens deve ir para armadilhas reais da base. Um exemplo é a decisão de manter todos os tipos em um único arquivo.

O critério de exclusão é claro: evite declarar o óbvio. Ou seja, deixe de fora aquilo que o Claude descobriria olhando o sistema de arquivos ou o repositório.

Quando houver um conjunto extenso de instruções sobre um tema recorrente, como verificação de trabalho, crie uma skill. Em seguida, referencie essa skill a partir do CLAUDE.md.

Skills

Skills funcionam como guias leves que ajudam o Claude a encontrar informação quando precisar. O erro comum é torná-las restritivas demais, algo que só se justifica em áreas de alta criticidade.

Para skills longas, aplique a divulgação progressiva internamente, dividindo o conteúdo em vários arquivos. Além disso, o valor real de uma skill está em codificar opiniões e práticas do seu time ou produto, e não conhecimento geral.

Referências

Você pode incluir arquivos como referência por menção direta, para que o Claude consulte informação aprofundada sobre o plano atual. Isso vale para especificações, mockups e até bases de código inteiras.

A Anthropic prefere referências em código, porque oferecem instrução de alta fidelidade em uma linguagem que o modelo domina. Por exemplo, um mockup em HTML tende a produzir resultados melhores do que uma descrição textual do design ou uma captura de tela.