Novas regras de engenharia de contexto para os modelos Claude 5

• No Claude Opus 5 e no Claude Fable 5, foi possível reduzir o prompt de sistema do Claude Code em mais de 80% sem queda mensurável de desempenho em avaliações de programação
• Regras detalhadas que evitavam os piores cenários em modelos anteriores podem entrar em conflito entre prompt de sistema, Skills, CLAUDE.md e solicitações do usuário; para modelos mais recentes, é melhor permitir o uso do contexto ao redor e do próprio julgamento
• Em vez de fornecer previamente todas as instruções e exemplos de ferramentas, aplica-se divulgação progressiva (progressive disclosure), com interfaces expressivas e carregamento de informações e ferramentas no momento necessário
• Recomenda-se manter no CLAUDE.md apenas armadilhas do repositório de forma concisa, separar instruções longas em Skills e usar materiais de referência ricos, como especificações, suítes de teste, protótipos HTML, código e rubricas de avaliação
• Com /doctor e claude doctor, é possível ajustar o tamanho de Skills e CLAUDE.md; o contexto dos modelos mais recentes deve ser estruturado para reduzir repetição e restrições excessivas e encontrar informações relevantes quando necessário

---

Engenharia de contexto além dos prompts

• Quando Claude processa uma mensagem, o prompt do usuário é parte do contexto total; o restante é montado a partir do prompt de sistema, Skills, CLAUDE.md, memória e outros elementos
• A engenharia de contexto se aplica de forma comum a várias solicitações, por isso é mais difícil escrevê-la de modo tão específico quanto um prompt individual, mas ela tem grande impacto nos resultados do Claude Code e de agentes próprios
• É preciso projetar prompts e instruções gerais sem saber de antemão quais serão as solicitações do usuário, e a abordagem adequada também muda à medida que as capacidades do Claude evoluem
• No Claude Opus 5 e no Claude Fable 5, mesmo removendo mais de 80% do prompt de sistema do Claude Code, não houve queda mensurável de desempenho em avaliações de programação
• Essa prática recomendada foi refletida no claude doctor; no Claude Code, é possível usar /doctor para ajustar Skills e CLAUDE.md a um tamanho adequado

Libertando o modelo de restrições excessivas

• O Claude Code existente sofria restrições excessivas não apenas no prompt de sistema, mas também no CLAUDE.md e nas Skills
  • Em uma mesma solicitação, instruções como “deixe a documentação apropriada” e “não adicione comentários” podem entrar em conflito por meio do prompt de sistema, das Skills e da solicitação do usuário
  • Mesmo que Claude consiga interpretar a intenção do usuário, instruções sobrepostas ou conflitantes o obrigam a raciocinar com mais cuidado antes de decidir como agir
• No passado, essas restrições eram necessárias para evitar os piores cenários, mas modelos mais recentes permitem remover várias delas e usar o contexto ao redor e o próprio julgamento
• As ferramentas que o Claude Code pode utilizar também aumentaram
  • Antes, o CLAUDE.md era o principal repositório de memória, informações e instruções
  • Hoje, memória, artefatos e Skills permitem carregar e compartilhar contexto entre sessões

Usar julgamento baseado em contexto em vez de regras fixas

• As primeiras versões do Claude Code incluíam instruções fortes, nem sempre adequadas, para impedir piores cenários como exclusão de arquivos
• O prompt de sistema anterior exigia não escrever comentários por padrão no código, proibia docstrings de vários parágrafos ou comentários de várias linhas e determinava não criar documentos de planejamento, decisão ou análise sem solicitação do usuário
• Essas regras podem ser inadequadas em algumas solicitações
  • O usuário pode ter preferências próprias de documentação
  • Certas partes de um código complexo podem exigir comentários de várias linhas
• Modelos antigos frequentemente escreviam comentários ruins sem proteções, o que tornava esse compromisso necessário, mas modelos mais recentes lidam melhor com essas decisões mesmo sem regras explícitas
• O novo prompt de sistema usa uma instrução baseada em contexto: “escreva código que pareça pertencer ao código ao redor e combine densidade de comentários, nomenclatura e expressões idiomáticas”

Projetar interfaces expressivas em vez de exemplos

• A regra central para uso de ferramentas no passado era fornecer exemplos de uso ao Claude
• Em modelos mais recentes, exemplos podem limitar o espaço de exploração a uma área específica; por isso, deve-se priorizar a expressividade da interface e dos parâmetros de ferramentas, scripts e arquivos
• Definir o status da ferramenta Todo como uma enumeração pending, in_progress, completed pode sugerir naturalmente a forma de uso
• A instrução de manter apenas um item como in_progress concretiza o comportamento solicitado no nível da interface

Divulgação progressiva: abrir informações no momento necessário

• No início, quando o Claude Code era focado em programação, métodos de revisão e verificação de código eram incluídos em detalhes no prompt de sistema
• Essas informações não eram sempre necessárias, mas eram importantes para certas tarefas
• Hoje, é possível usar divulgação progressiva para carregar o contexto apropriado no momento necessário
  • Mover instruções de verificação e revisão de código para Skills separadas, permitindo que o Claude Code as invoque seletivamente
  • Algumas ferramentas são carregadas sob demanda, e o agente precisa pesquisar a definição completa com ToolSearch antes de usá-las
  • É possível oferecer muitas ferramentas, como a ferramenta Task, sem que elas ocupem contexto antes de serem necessárias
• Não é preciso transformar CLAUDE.md e Skill.md em um repositório central de todas as práticas possíveis
• Em vez disso, eles podem ser organizados como uma árvore de arquivos carregada conforme necessário; essa abordagem também é tratada em harnesses de workflow dinâmicos por tarefa

Consolidar instruções repetidas em descrições simples de ferramentas

• Modelos Claude anteriores às vezes exigiam repetição da mesma instrução e também tendiam a seguir melhor instruções no fim do contexto do que no início
• Por isso, as mesmas instruções ou exemplos de uso de ferramentas eram colocados tanto no corpo do prompt de sistema quanto nas descrições das ferramentas
• Em modelos mais recentes, é possível remover exemplos repetidos e colocar o uso da ferramenta apenas na descrição da ferramenta

Transição do CLAUDE.md para memória automática

• No passado, o atalho # escrevia informações automaticamente no CLAUDE.md, incentivando o usuário a salvar manualmente a memória do Claude
• Hoje, Claude memoriza automaticamente informações relevantes para a tarefa e para o usuário

Materiais de referência ricos além de especificações simples

• O Claude Code no modo de planejamento dependia fortemente de arquivos de plano em Markdown para consulta posterior quando necessário, e projetos longos às vezes armazenavam especificações dentro da base de código
• O Claude mais recente consegue lidar com materiais de referência em formatos mais complexos
  • Artefatos HTML criados com o novo recurso de artefatos
  • Código, como funções a serem portadas de outra base de código
  • Especificações expressas como uma suíte de testes detalhada
• Uma rubrica é outro formato de referência que permite ao Claude tentar e verificar preferências ou critérios de qualidade de uma área específica
  • É possível definir critérios como o que é um bom design de API
  • Por meio de workflows dinâmicos, é possível criar um agente de verificação que use essa rubrica

Papéis por componente de contexto

• Prompt de sistema

  • Está intimamente ligado ao contexto do produto e informa ao Claude em qual produto ele está e que trabalho está realizando
  • Usuários do Claude Code raramente precisarão modificá-lo, mas, se você estiver criando seu próprio harness de agente, essa é uma área que exigirá bastante tempo

• CLAUDE.md

  • Deve ser mantido leve e descrever brevemente a finalidade do repositório, mas a maior parte dos tokens deve ser usada para registrar armadilhas a observar na base de código
  • Vale a pena registrar uma regra de repositório que coloque todos os tipos em um único arquivo
  • Evite informações óbvias que Claude possa descobrir examinando o sistema de arquivos ou o repositório
  • Se houver várias instruções específicas para verificação de tarefas, crie uma Skill de verificação e aplique divulgação progressiva referenciando-a no CLAUDE.md

• Skills

  • Devem ser compostas como guias leves que ajudam Claude a encontrar informações quando necessário
  • A menos que seja uma área muito importante, deve-se evitar restrições excessivas
  • Skills longas são melhores quando divididas em vários arquivos para serem carregadas progressivamente
  • São mais úteis para conter opiniões, conhecimento e práticas recomendadas específicas de uma pessoa, equipe ou produto

• Materiais de referência

  • Mencionar um arquivo com @ permite que Claude verifique informações detalhadas relacionadas ao plano atual
  • Arquivos de especificação, protótipos e bases de código inteiras também podem ser materiais de referência
  • Em geral, é melhor priorizar arquivos em forma de código, pois código fornece instruções claras e fiéis em uma linguagem que Claude conhece bem
  • Protótipos de design em HTML geralmente produzem resultados melhores do que descrições de design ou capturas de tela

Simplificação do contexto existente

• É preciso simplificar o contexto removendo regras, repetições e informações desnecessárias de prompts de sistema, Skills e CLAUDE.md
• O comando claude doctor oferece suporte automático a esse trabalho de simplificação
• Técnicas de prompting para modelos avançados podem ser vistas em mais detalhes no guia de campo do Claude Fable