Anthropic altera regras de engenharia de contexto para a geração Claude 5

O engenheiro Thariq Shihipar, membro da equipe técnica da Anthropic, publicou um guia detalhado sobre a evolução da engenharia de contexto para os modelos da geração Claude 5 e a ferramenta Claude Code. O documento oficializa uma virada fundamental na forma como desenvolvedores e arquitetos de sistemas baseados em inteligência artificial devem construir seus prompts de sistema, descrições de ferramentas e arquivos de configuração como o CLAUDE.md.

A mudança de paradigma apresentada pela Anthropic derruba práticas que haviam se tornado quase dogmáticas na comunidade de desenvolvimento de IA. O diagnóstico de Thariq Shihipar aponta que muitas das orientações antigas foram superadas pelos avanços na capacidade de julgamento autônomo e no raciocínio dos novos modelos, tornando as regras rígidas do passado não apenas obsoletas, mas potencialmente prejudiciais ao desempenho do sistema.

Historicamente, a engenharia de contexto baseava-se em impor limites severos para evitar comportamentos indesejados nas execuções de código e chamadas de API. No entanto, com a chegada da geração Claude 5, a equipe da Anthropic comprovou que simplificar as instruções centrais e transferir a responsabilidade para a capacidade avaliativa do próprio modelo produz resultados significativamente mais precisos e flexíveis em ambientes complexos de desenvolvimento de software.

Mudar de regras para julgamento

Quando o ecossistema Claude Code foi lançado originalmente, a preocupação primária da equipe de engenharia da Anthropic era garantir que o modelo não causasse estragos irreversíveis no ambiente de desenvolvimento, como a exclusão acidental de arquivos críticos ou a geração de documentação excessiva e irrelevante. Para contornar as limitações de julgamento das versões anteriores do modelo, o prompt do sistema continha proteções e travas extremamente rígidas.

Essas travas de segurança forçavam o modelo a seguir diretrizes absolutas que frequentemente falhavam em cenários de uso mais específicos. O prompt de sistema antigo do Claude Code continha instruções expressas que proibiam o modelo de criar comentários longos ou documentos intermediários de análise, impondo uma sintaxe minimalista a qualquer custo para evitar alucinações ou perda de contexto.

In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.

Essa abordagem criava um dilema técnico inevitável. Em bases de código complexas ou em tarefas que exigiam explicações detalhadas em trechos sensíveis, as restrições impostas no prompt do Claude Code impediam o modelo de gerar a documentação necessária. A equipe da Anthropic precisava aceitar essa limitação porque os modelos antigos, sem essas amarras, tendiam a gerar comentários incorretos ou em excesso. O cenário mudou radicalmente com os novos modelos da geração Claude 5, cuja capacidade de discernimento permite entender o estilo do projeto sem depender de regras arbitrárias.

O novo prompt de sistema adotado no Claude Code abandona as proibições absolutas e adota uma instrução focada em mimetismo e adaptação contextual. Em vez de ditar o tamanho exato dos comentários, o sistema instrui o modelo a analisar o código existente e reproduzir o mesmo padrão do repositório do desenvolvedor.

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

A transição de um modelo baseado em proibições para um modelo focado no julgamento contextual demonstra que a geração Claude 5 é capaz de avaliar dinamicamente a densidade de comentários, as convenções de nomenclatura e os idiomas específicos de cada linguagem de programação sem a necessidade de direcionamento rígido no prompt inicial.

Design de ferramentas e interfaces

A regra de ouro tradicional para o uso de ferramentas por agentes de IA era fornecer múltiplos exemplos de execução no próprio prompt. No entanto, os testes conduzidos por Thariq Shihipar e pela equipe da Anthropic revelaram que apresentar exemplos detalhados para os novos modelos gera um efeito colateral adverso: os exemplos restringem o espaço de exploração do modelo, fazendo com que ele imite cegamente os casos fornecidos em vez de raciocinar sobre a melhor solução técnica.

Em vez de gastar tokens preenchendo o contexto com exemplos de chamadas de API, a nova diretriz da Anthropic exige que os engenheiros foquem na expressividade e no design arquitetônico das ferramentas, rotinas e scripts disponibilizados para o modelo. A clareza dos parâmetros aceitos pelas ferramentas passou a ser o fator determinante para a correta execução do agente.

Um caso prático citado no artigo envolve a implementação da ferramenta de gerenciamento de tarefas Todo. Em vez de escrever instruções longas exemplificando como alternar o status de uma tarefa, a engenharia da Anthropic estruturou o parâmetro de status como uma enumeração simples entre os estados pending, in_progress e completed.

A simples presença dessa enumeração detalhada na definição da ferramenta indica ao Claude 5 como interagir com a interface. Adicionalmente, uma instrução direta solicitando que apenas um item permaneça no estado in_progress por vez foi suficiente para definir com precisão o comportamento desejado do agente, dispensando completamente a inclusão de exemplos sintáticos adicionais.

Essa reformulação na forma de projetar interfaces para agentes reduz drasticamente a latência das chamadas e economiza janelas de contexto valiosas, permitindo que a geração Claude 5 interprete o funcionamento de ferramentas complexas unicamente a partir de definições de tipos e esquemas estruturados com clareza.

O conceito de divulgação progressiva

Nas primeiras versões do Claude Code, o foco exclusivo em tarefas de programação fazia com que o prompt de sistema contivesse instruções detalhadas e contínuas sobre metodologias de revisão de código, checagem de erros e protocolos de verificação. Esse volume de dados permanecia carregado na memória operacional do modelo mesmo quando o usuário estava apenas realizando perguntas simples sobre a estrutura do projeto.

A evolução do ecossistema Claude Code introduziu o conceito de divulgação progressiva (progressive disclosure), uma técnica que consiste em carregar informações contextuais profundas apenas no momento exato em que elas se tornam estritamente necessárias para o cumprimento de uma tarefa.

Para aplicar esse conceito, a equipe da Anthropic isolou os procedimentos pesados de verificação e revisão de código em habilidades (skills) independentes. Em vez de inflar o prompt principal, o Claude Code agora invoca dinamicamente essas habilidades específicas apenas quando detecta a necessidade de validar uma alteração estrutural no código.

O mecanismo de divulgação progressiva não se limita ao carregamento de habilidades, estendendo-se também à gestão de ferramentas do agente através de um recurso chamado carregamento postergado (deferred loading). Sob essa arquitetura, ferramentas como as Task tools não têm suas definições completas injetadas no contexto inicial. Em seu lugar, o agente utiliza uma ferramenta de busca especializada chamada ToolSearch para localizar e carregar os esquemas completos apenas quando decide utilizá-los.

Essa abordagem resolve um dos maiores gargalos da engenharia de contexto anterior, que consistia em lotar o arquivo de configuração CLAUDE.md ou os arquivos Skill.md com todo o conhecimento cumulativo da empresa. O mito de criar um repositório centralizado contendo cada exceção e regra de negócio no CLAUDE.md foi substituído pela criação de uma árvore de arquivos interconectados que são lidos dinamicamente conforme a demanda da aplicação.

Substituindo repetições por descrições

Modelos de linguagem mais antigos apresentavam uma limitação conhecida de atenuação de atenção, na qual instruções localizadas no meio da janela de contexto podiam ser ignoradas. Por esse motivo, era comum ver prompts de sistema que repetiam a mesma instrução várias vezes ou reservavam o final da janela de contexto para reforçar ordens cruciais.

Dentro da arquitetura do Claude Code, essa limitação fazia com que as instruções sobre como utilizar uma determinada ferramenta estivessem duplicadas: elas apareciam tanto no prompt de sistema principal quanto dentro da própria descrição do parâmetro da ferramenta.

A engenharia da Anthropic confirmou que a geração Claude 5 eliminou a necessidade dessa redundância. Os testes demonstraram que o modelo processa com a mesma precisão diretrizes localizadas no início, meio ou fim do contexto, permitindo a eliminação completa das repetições que poluíam o prompt do sistema.

Com essa alteração, todas as instruções operacionais de uma ferramenta foram movidas do prompt de sistema principal diretamente para a descrição individual da ferramenta. Essa limpeza estrutural diminuiu a complexidade do prompt global e aumentou a previsibilidade das respostas do modelo.

O ganho de eficiência ao remover trechos duplicados permitiu que os desenvolvedores focassem o prompt de sistema estritamente no propósito de negócio do produto, deixando a mecânica sintática das chamadas contida de forma modularizada dentro de cada interface registrada.

O uso de memória automática

Em versões anteriores das ferramentas de linha de comando da Anthropic, a persistência de preferências do desenvolvedor exigia uma ação manual frequente. Os usuários eram orientados a utilizar o atalho de teclado com o caractere # para gravar manualmente trechos da conversa ou regras de estilo diretamente no arquivo CLAUDE.md.

Esse fluxo manual apresentava fricção e frequentemente resultava em arquivos CLAUDE.md desorganizados, cheios de anotações temporárias que perdiam a relevância ao longo do desenvolvimento do projeto.

Com os novos modelos, o sistema passou a utilizar o recurso de memória automática (auto-memory). O próprio Claude 5 identifica informações relevantes sobre o fluxo de trabalho, o estilo do desenvolvedor e as especificidades da infraestrutura durante a interação, salvando essas memórias de forma autônoma e contextualizada.

A automação do processo de salvamento garante que o contexto do repositório permaneça atualizado com informações genuinamente úteis, sem exigir que o programador interrompa seu raciocínio para gerenciar arquivos de texto de configuração manualmente através do atalho #.

Estruturação avançada de referências

Durante as fases iniciais de planejamento técnico no Claude Code, o ecossistema dependia fortemente de arquivos em formato Markdown simples contendo planos de execução. Manter esses arquivos salvos no repositório era a forma padrão de garantir que o modelo mantivesse o alinhamento com a arquitetura desejada durante projetos de longa duração.

A nova geração de modelos é capaz de processar referências de contexto infinitamente mais ricas e complexas do que simples documentos de texto contendo listas de tarefas em Markdown.

Entre as formas mais avançadas de referência validadas por Thariq Shihipar está a utilização de artefatos HTML gerados pelo novo recurso de artifacts da plataforma. Em vez de descrever um layout ou uma interface de usuário com texto explicativo ou capturas de tela, fornecer um mockup em HTML entrega ao modelo um código de alta fidelidade escrito na própria linguagem em que a interface será construída.

Outra forma altamente eficaz de referência é a entrega de código-fonte funcional como especificação. Isso inclui o envio de suítes completas de testes automatizados para servirem como especificação comportamental, ou mesmo a inclusão de funções pertencentes a outros repositórios para que o Claude 5 realize o port ou a adaptação arquitetônica com precisão.

O relatório da Anthropic também destaca o uso de rúbricas (rubrics) como referências dinâmicas. As rúbricas permitem que o Claude 5 avalie critérios subjetivos do desenvolvedor — como o padrão estético de um bom design de API — por meio do disparo de fluxos de trabalho dinâmicos que instanciam agentes verificadores (verifier agents) programados para validar o código em relação a essas rúbricas.

Organização prática do contexto

Para consolidar essas mudanças, Thariq Shihipar estruturou a anatomia ideal de um projeto que utiliza a tecnologia da Anthropic, dividindo as responsabilidades de contexto em quatro pilares fundamentais: System Prompt, CLAUDE.md, Skills e References.

O System Prompt deve ser estritamente vinculado ao contexto do produto final. Ele estabelece em qual ambiente a aplicação está sendo executada e qual é o seu objetivo primário. Para quem utiliza o Claude Code diretamente como ferramenta, este prompt raramente será alterado, mas desenvolvedores que constroem suas próprias plataformas de agentes (agent harnesses) devem focar a maior parte do tempo na calibração deste elemento.

O arquivo CLAUDE.md deve ser mantido de forma extremamente enxuta. Ele deve conter apenas uma breve descrição sobre o propósito do repositório, gastando a maior parte do seu limite de tokens na explicação de particularidades não óbvias da base de código (gotchas) — como a exigência de manter todas as definições de tipos em um único arquivo monolítico. Instruções óbvias que podem ser deduzidas pela simples leitura do sistema de arquivos devem ser sumariamente removidas.

As Skills funcionam como guias leves que auxiliam o modelo a encontrar informações específicas quando solicitado. Elas devem codificar práticas, opiniões e metodologias particulares da equipe de desenvolvimento ou do produto. Quando uma habilidade se torna muito extensa, a orientação é aplicar a divulgação progressiva, dividindo-a em múltiplos arquivos interligados.

Por fim, as References são incluídas nas conversas por meio de menções com o caractere @. Esse recurso permite incluir especificações, mockups em HTML ou bases de código inteiras para apoiar o plano de execução atual do modelo, fornecendo instruções estruturadas na linguagem nativa do sistema.

Otimização com claude doctor

Para auxiliar os desenvolvedores na transição e simplificação dos seus ambientes de desenvolvimento, a Anthropic lançou um novo comando para a interface de linha de comando chamado claude doctor. A ferramenta analisa automaticamente o repositório, identificando regras duplicadas no prompt de sistema, referências obsoletas e oportunidades para aplicar a divulgação progressiva.

O comando claude doctor atua diretamente na limpeza do CLAUDE.md e na reorganização das habilidades cadastradas, reduzindo o consumo de tokens desnecessários e otimizando a velocidade de resposta nas chamadas da API.

Para engenheiros que buscam um aprofundamento adicional no desenvolvimento de prompts para modelos de raciocínio avançado, Thariq Shihipar recomenda a leitura do guia de campo Fable field guide, publicado pela equipe técnica da Anthropic como material complementar a estas novas diretrizes.