Já escrevi anteriormente sobre como dar os melhores prompts para a nova geração de modelos Claude 5 e trabalhar iterativamente com eles para descobrir o que você quer construir.
Mas quando você envia uma mensagem para o Claude, o prompt é apenas uma pequena parte do contexto que ele recebe. Grande parte do seu contexto é montada a partir do seu prompt de sistema, Skills, arquivos CLAUDE.md, memória e outras fontes. Chamamos isso de engenharia de contexto, e ela causa um grande impacto nos resultados que você gera ao usar o Claude Code ou ao construir seus próprios agentes.
Diferente de um prompt, o contexto é usado de forma geral em muitas requisições, então não pode ser tão específico. Como você constrói esses prompts e orientações gerais para o Claude, especialmente quando não sabe qual pode ser o prompt do usuário?
Isso pode ser surpreendentemente difícil, à medida que as próprias capacidades do Claude evoluem. Recentemente, notamos um grande salto na forma como fazemos prompting para a nova geração de modelos Claude. Removemos mais de 80% do prompt de sistema do Claude Code para modelos como Claude Opus 5 e Claude Fable 5 sem perda mensurável em nossas avaliações de codificação.
Aqui está o que aprendemos sobre prompting para essa nova classe de modelos e como você pode usar isso para atualizar sua engenharia de contexto. Colocamos essas melhores práticas no claude doctor; use o comando /doctor no Claude Code para ajustar suas Skills e arquivos CLAUDE.md.
Libertando o Claude
No geral, descobrimos que estávamos super-restritivos com o Claude Code, tanto através do nosso prompt de sistema quanto em nossos arquivos CLAUDE.md e Skills.
Por exemplo, quando lemos transcrições do nosso próprio uso interno do Claude Code, vemos várias mensagens conflitantes em uma única requisição, como "deixe documentação conforme apropriado" ou "NÃO adicione comentários", enquanto nosso prompt de sistema, Skills e requisições do usuário entram em conflito.
Geralmente, o Claude consegue interpretar a intenção do usuário para chegar à resposta correta, mas ele precisa pensar com mais cuidado sobre essas mensagens sobrepostas e conflitantes antes de decidir o que fazer.
E embora essas restrições fossem necessárias para evitar os piores cenários, desde então descobrimos que podemos deletar muitas delas e deixar o modelo usar o contexto ao redor e seu julgamento.
Além disso, o Claude Code agora tem muito mais ferramentas. O Claude costumava depender do CLAUDE.md como fonte de memória, informação e orientação. Agora temos memória, artefatos e Skills, que o Claude pode usar para criar novas formas de carregar e compartilhar contexto entre sessões.
Antes e agora
Havia várias práticas recomendadas de engenharia de contexto que se tornaram mitos. Incluindo:
**
Antes: Dar regras ao Claude
Agora: Deixar o Claude usar julgamento
**Quando lançamos o Claude Code pela primeira vez, precisávamos ter certeza de que o Claude evitaria os piores cenários, como deletar arquivos. Isso significava dar orientações particularmente fortes que nem sempre seriam verdadeiras. Por exemplo, no prompt de sistema, costumávamos dizer:
No código: por padrão, não escreva comentários. Nunca escreva docstrings de vários parágrafos ou blocos de comentários de várias linhas — no máximo uma linha curta. Não crie documentos de planejamento, decisão ou análise a menos que o usuário peça — trabalhe a partir do contexto da conversa, não de arquivos intermediários.
Mas para um certo subconjunto de prompts, essa orientação estaria errada. No caso de documentação, o usuário pode ter suas próprias preferências, ou partes específicas de código muito complexo podem precisar de blocos de comentários de várias linhas.
Ainda assim, sem essas salvaguardas para modelos mais antigos, os comentários que o Claude escrevia estariam incorretos em muitos casos, e tínhamos que aceitar essa troca. Mas modelos mais novos têm melhor julgamento e podem lidar com essas decisões bem, sem regras explícitas.
No novo prompt de sistema, dizemos: Escreva código que se pareça com o código ao redor: combine a densidade de comentários, nomenclatura e estilo.
**Antes: Dar exemplos ao Claude
Agora: Projetar interfaces
**A regra número um para o uso de ferramentas era dar exemplos ao Claude de como usá-las. Com nossos modelos mais recentes, descobrimos que dar exemplos na verdade os restringe a um certo espaço de exploração.
Em vez de usar exemplos, pense mais no design das suas ferramentas, scripts e arquivos — quais parâmetros o Claude tem e como eles podem ser mais expressivos?
Por exemplo, no exemplo da ferramenta Todo, apenas listar o status como uma enumeração entre pendente, em_andamento e concluído, dá dicas ao Claude sobre como usá-la. A instrução de manter um item em_andamento ajuda a definir o comportamento solicitado.
**Antes: Colocar tudo no início
Agora: Usar divulgação progressiva**
Como o Claude Code era focado em codificação, nosso prompt de sistema incluía informações detalhadas sobre como fazer revisão e verificação de código. Isso nem sempre era necessário, mas quando era, era informação crucial.
Desde então, o Claude Code se tornou muito competente em usar divulgação progressiva — carregar o contexto certo no momento certo. Por exemplo, movemos verificação e revisão de código para suas próprias Skills que o Claude Code poderia chamar seletivamente.
Mas a divulgação progressiva não é apenas para Skills, também a usamos para ferramentas. Algumas de nossas ferramentas são de 'carregamento adiado', o que significa que o agente deve procurar suas definições completas usando o ToolSearch antes de usá-las. Isso nos permite ter mais ferramentas (como nossas ferramentas de Tarefa) que não ocupam contexto até serem necessárias.
O mesmo pode ser aplicado aos seus próprios arquivos CLAUDE.md e Skill.md. Um mito comum é que você deve fazer deles um repositório central para todas as práticas conhecidas que você pode encontrar, porque o Claude não as encontraria de outra forma. Em vez disso, considere ter uma árvore de arquivos que pode ser carregada no momento certo.
**Antes: Repetir-se
Agora: Descrições simples de ferramentas**
Modelos Claude anteriores às vezes precisavam de instruções repetidas ou eram mais propensos a ouvir instruções no final da janela de contexto do que no início. Isso significava que nosso prompt de sistema às vezes tinha referências a ferramentas no prompt de sistema principal, bem como instruções na descrição da ferramenta.
Descobrimos que podíamos deletar esses exemplos repetidos e colocar instruções sobre como usar ferramentas nas descrições das ferramentas, em vez de no prompt de sistema.
**Antes: Memória em arquivos CLAUDE.md
Agora: Memória automática**
Costumávamos incentivar os usuários a salvar coisas na memória do Claude, usando a tecla # para escrever automaticamente no CLAUDE.md. Em vez disso, agora o Claude salva automaticamente memórias relevantes para o trabalho e para você.
**Antes: Especificações simples
Agora: Referências ricas**
No modo de plano, o Claude Code dependia fortemente de arquivos markdown com planos. Armazenar esses arquivos como planos ajudava o Claude a consultá-los quando necessário. Outra prática recomendada similar era armazenar especificações no repositório para o Claude consultar enquanto trabalhava em projetos mais longos.
Mas descobrimos que o Claude pode lidar com referências cada vez mais complicadas. Em vez de arquivos markdown simples, o Claude pode referenciar artefatos HTML criados pelo nosso novo recurso de artefatos.
Você também pode dar ao Claude referências na forma de código. Uma especificação pode ser também um conjunto de testes detalhado, ou uma função em um repositório diferente que o Claude possa portar.
Rubricas são outra forma de referência. Rubricas permitem que o Claude tente verificar seu gosto em um campo particular (ex.: como é um bom design de API) usando workflows dinâmicos e criando agentes verificadores com essas rubricas.
Aplicando isso ao seu contexto
Juntando tudo isso, como fica quando você monta seu contexto?
**Prompt de Sistema
**Um prompt de sistema está fortemente ligado ao contexto do produto. Ele diz ao Claude em qual produto ele está operando e o que está fazendo. Para o Claude Code, você provavelmente nunca modificará isso, mas se estiver construindo sua própria estrutura de agente, é aqui que você deve gastar muito tempo.
**CLAUDE.md
**Mantenha seu CLAUDE.md leve e descreva brevemente para que serve seu repositório, mas gaste a maior parte dos tokens em pegadinhas dentro do repositório. Por exemplo, você pode organizar seu código para manter tipos em um arquivo monolítico e em nenhum outro lugar. Evite afirmar o 'óbvio' que o Claude deveria saber olhando para seu sistema de arquivos ou repositório.
Use divulgação progressiva para mais detalhes, por exemplo, se você tem várias instruções únicas sobre como verificar seu trabalho, crie uma Skill de verificação e faça referência a ela a partir do seu CLAUDE.md.
**Skills
**Pense nas Skills como guias leves para o Claude encontrar informações quando necessário. Evite torná-las super-restritivas, exceto em áreas altamente importantes.
Para Skills longas, tente usar divulgação progressiva o máximo possível — divida em vários arquivos e separe-os.
É melhor quando as Skills codificam opiniões, conhecimentos ou melhores práticas específicas que são particulares para você, sua equipe ou produto.
**Referências
**Você pode usar @ para mencionar arquivos e incluí-los como referências. Referências permitem que o Claude consulte informações detalhadas sobre o plano atual.
Isso pode ser em arquivos de especificações, maquetes, ou até mesmo repositórios inteiros. Geralmente, você deve preferir arquivos que estão em código, pois fornecem instruções claras e de alta fidelidade ao Claude em uma linguagem que ele conhece muito bem. Por exemplo, uma maquete HTML de um design geralmente produzirá melhores resultados do que uma descrição do design ou uma captura de tela.
Tente simplificar
Em todo o seu prompt de sistema, Skills e arquivos CLAUDE.md, você pode precisar simplificar, assim como fizemos. Lançamos um novo comando chamado claude doctor, que ajudará você a fazer isso automaticamente também. Para mais detalhes sobre como fazer prompting para modelos mais avançados especificamente, confira nosso guia de campo Fable.
