Já escrevi anteriormente sobre como dar instruções para a nova geração de modelos Claude 5 e trabalhar com eles de forma iterativa 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 isso causa um grande impacto nos resultados que você gera ao usar o Claude Code ou ao construir seus próprios agentes.
Ao contrário de um prompt, o contexto é usado de forma geral em muitas solicitaçõ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. Mais recentemente, notamos um grande salto na forma como instruímos 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 como instruir esta 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 restringindo demais o Claude Code, tanto através do nosso prompt de sistema quanto nos 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 solicitação, como "deixe documentação conforme apropriado" ou "NÃO adicione comentários", enquanto nosso prompt de sistema, Skills e solicitações de usuários entram em conflito.
Geralmente, o Claude consegue interpretar a intenção do usuário para chegar à resposta correta, mas precisa pensar mais cuidadosamente sobre essas mensagens sobrepostas e conflitantes antes de decidir o que fazer.
E embora essas restrições fossem necessárias para evitar cenários de pior caso, desde então descobrimos que podemos deletar muitas delas e deixar o modelo usar o contexto ao redor e seu próprio 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 o julgamento
**Quando lançamos o Claude Code pela primeira vez, precisávamos ter certeza de que o Claude evitasse cenários de pior caso, como deletar arquivos. Isso significava que dávamos orientações particularmente fortes que nem sempre eram 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 com 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 os 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 estava errada. No caso de documentação, o usuário pode ter suas próprias preferências, ou partes específicas de um código muito complexo podem precisar de blocos de comentários com 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 os 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 leia como o código ao redor: combine sua densidade de comentários, nomenclatura e expressão idiomática.
**Antes: Dar exemplos ao Claude
Agora: Projetar interfaces
**A regra número um para o uso de ferramentas era dar exemplos ao Claude sobre 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 de 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. Elas nem sempre eram necessárias, mas quando eram, era informação crucial.
Desde então, o Claude Code se tornou muito competente em usar divulgação progressiva — carregando o contexto certo nos momentos certos. Por exemplo, movemos a 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ê quer fazer deles um repositório central para cada prática conhecida que você pode encontrar, porque o Claude não a 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 de ferramentas simples**
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 de atalho # para escrever automaticamente no CLAUDE.md. Em vez disso, agora o Claude salva automaticamente memórias que são relevantes para o trabalho e para você.
**Antes: Especificações simples
Agora: Referências ricas**
No modo de planejamento, 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 semelhante era armazenar especificações na base de código para o Claude consultar enquanto trabalha 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 também pode ser um conjunto de testes detalhado, ou uma função em uma base de código 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 (por exemplo, como é um bom design de API) usando fluxos de trabalho 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 está operando e o que está fazendo. Para o Claude Code, você provavelmente nunca modificará isso, mas se estiver construindo seu próprio harness 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 maioria dos tokens em pegadinhas dentro da base de código. Por exemplo, você pode organizar seu código para manter tipos em um único arquivo monolítico e em nenhum outro lugar. Evite declarar coisas 'óbvias' que o Claude deveria saber olhando para seu sistema de arquivos ou seu 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 permitir que o Claude encontre informações quando necessário. Evite torná-las excessivamente restritivas, exceto em áreas altamente importantes.
Para Skills longas, tente usar divulgação progressiva o máximo possível — divida-as em muitos arquivos e separe-os.
É melhor quando as Skills codificam opiniões, conhecimentos ou melhores práticas particulares que são específicos para você, sua equipe ou produto.
**Referências
**Você pode usar @ mencionar arquivos para 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é bases de código inteiras. 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 o ajudará a fazer isso automaticamente também. Para mais detalhes sobre como instruir modelos mais avançados especificamente, confira nosso guia de campo do Fable.
