CLAUDE.md depois do Opus 5: porque as instruções longas atrapalham agora o Claude

Encontrará informações sobre como trabalhar com o Ailoot na documentação.

O que mudou no Claude após o lançamento do Opus 5?#

O Opus 5 foi lançado a 24 de julho de 2026 e tornou-se imediatamente o modelo predefinido no Claude Code. O modelo em si — o preço, os benchmarks e os modos de esforço — é abordado em pormenor num guia separado, «Deve mudar para o Claude Opus 5?». Este artigo trata de outra coisa: o lançamento do modelo também mudou a forma de comunicar com ele eficazmente.

A Anthropic publicou uma análise no blogue do Claude. A ideia principal é a seguinte:

A expressão-chave é «limitar demasiado». Quando os modelos eram mais fracos, precisavam de apoio: faz isto, não faças aquilo, aqui está um exemplo, repete mais uma vez. O Opus 5 já não precisa desse apoio e, pior ainda, este pode começar a atrapalhá-lo. A Anthropic enuncia simplesmente o novo princípio: deixe o Claude usar o seu próprio discernimento.

O que significa isto na prática para si?

• O seu CLAUDE.md é o mesmo tipo de prompt de sistema, mas para o seu projeto. Se a Anthropic reduziu o seu em 80 por cento, o seu provavelmente também está demasiado extenso.
• As listas longas de regras já não garantem que sejam cumpridas. Pelo contrário, quanto mais linhas houver, menos rigorosamente o modelo as segue (mais abaixo, abordaremos este tema com dados da documentação).
• Surgiram novos mecanismos — memória automática e competências — que assumem parte do trabalho que antes tinha de explicitar manualmente no CLAUDE.md.

A ideia principal: o trabalho mais importante acontece antes do prompt — naquilo que coloca no contexto do modelo antes do primeiro pedido. A atualização do Opus 5 é essencialmente a confirmação oficial da Anthropic da mesma ideia. Desta vez, porém, vem acompanhada de números concretos e ferramentas novas. Vou abordar cada uma delas.

Porque é que um CLAUDE.md longo atrapalha agora?#

É assim que funciona. O CLAUDE.md é um ficheiro de regras que o Claude lê no início de cada sessão. Um guia separado, «Como configurar o CLAUDE.md», explica como criar um de raiz; este artigo aborda o inverso: o que remover agora. Tudo o que escrever aí entra no contexto antes do primeiro pedido e permanece lá ao longo de toda a conversa. O contexto não é infinito — e cada linha de regras ocupa espaço que poderia ser usado para a sua tarefa.

A documentação do Claude Code é direta:

O segundo ponto é mais importante do que o primeiro: os ficheiros longos reduzem o cumprimento das instruções. O modelo começa a prestar-lhes menos atenção. Esta é uma armadilha em que quase todos os principiantes caem. A lógica parece irrefutável: quero que o Claude me ouça, por isso vou escrever mais regras. Na prática, acontece o contrário. Quanto mais longa for a lista, mais dispersa fica a atenção do modelo e mais vezes este ignora uma regra.

Eis como a abordagem mudou:

Há também um segundo problema: as contradições. À medida que o ficheiro cresce, quase inevitavelmente acumula regras incompatíveis. Num sítio diz «escreva sempre testes» e noutro «não toque na pasta dos testes». A documentação avisa que, se duas regras se contradisserem, o Claude pode escolher qualquer uma delas ao acaso. Por outras palavras, um ficheiro demasiado extenso torna o comportamento do modelo menos previsível.

Uma regra simples: o CLAUDE.md é uma nota curta sobre aquilo que o Claude não consegue inferir por si. Tudo o que ultrapasse isso só lhe ocupa a atenção.

O que deve manter no CLAUDE.md e o que deve remover?#

A documentação apresenta um critério claro para decidir se uma regra merece um lugar no CLAUDE.md. Acrescente-a se:

1. O Claude tiver cometido o mesmo erro pela segunda vez.
2. Uma verificação do código tiver detetado algo que o modelo devia saber sobre este projeto.
3. Estiver a escrever a mesma correção no chat pela segunda vez.
4. Uma nova pessoa na equipa precisar do mesmo contexto para não estragar o projeto.

O princípio geral é manter problemas específicos do projeto e remover o que for óbvio. O Claude Code tem até uma verificação integrada, claude doctor, que sugere a limpeza de um CLAUDE.md demasiado extenso. Remove os detalhes que o modelo consegue inferir da base de código — estrutura de pastas, lista de dependências, visão geral da arquitetura — e mantém os problemas, a justificação e as convenções que diferem das predefinições.

A segunda regra importante é a especificidade. As formulações vagas não funcionam. Compare:

A diferença é simples. O modelo pode interpretar «formate corretamente» como quiser. «Use uma indentação de 2 espaços» pode ser verificado sem ambiguidade. Todas as regras do CLAUDE.md devem ser visíveis e verificáveis — isto é, deve ser possível perceber se foram ou não cumpridas.

Em terceiro lugar, remova o que é óbvio. Se escrever «escreva código limpo» ou «siga as boas práticas» no CLAUDE.md, isso é ruído. O modelo já sabe essas coisas, e a linha ocupa espaço e dispersa a sua atenção. A Anthropic aconselha explicitamente a não gastar contexto com coisas óbvias.

Para onde deve passar as regras que não cabem no CLAUDE.md?#

É aqui que entra a ferramenta mais subestimada. Se antes todas as instruções tinham de ficar no CLAUDE.md, agora os procedimentos longos têm um lugar próprio: as competências. Um guia separado, «Como escolher competências do Claude Code», explica como escolher as certas sem acrescentar demasiadas.

A diferença é fundamental. O CLAUDE.md é carregado na íntegra no início de cada sessão. Uma competência não. A documentação explica-o assim:

Isto chama-se divulgação progressiva — carregar informação conforme necessário. A ideia é fornecer contexto ao modelo por partes e no momento certo. A Anthropic passou as instruções detalhadas — por exemplo, as instruções para revisão de código — para competências e removeu-as do prompt de sistema.

O critério para passar algo para uma competência é simples: uma secção do CLAUDE.md passou de facto a procedimento. Uma nota de uma linha, «As compilações são executadas através de npm run build», é um facto e pertence ao CLAUDE.md. Dez passos sobre «como publicamos o projeto» são um procedimento e pertencem a uma competência.

Um princípio prático: passe para uma competência tudo o que fizer mais do que algumas vezes. Explique uma vez como prepara, por exemplo, o relatório semanal de um cliente, transforme essa explicação numa competência e não terá de a repetir. A competência fica disponível sem ocupar contexto e pode ser chamada pelo nome com um comando como /otchet.

É útil passar para competências:

• Procedimentos com várias etapas (publicação, elaboração de um relatório, verificações antes de uma versão).
• Instruções longas de que raramente precisa, mas de que precisa na íntegra.
• Tudo o que copiar de um chat para outro pela segunda ou terceira vez.

Há também uma opção intermédia: regras específicas de pastas. Se uma instrução só for importante para uma parte do projeto, pode colocá-la em .claude/rules/ e associá-la aos ficheiros relevantes. Assim, só é carregada quando o Claude trabalha com esses ficheiros, em vez de estar sempre no contexto.

O que é a memória automática e porque usá-la em 2026?#

O segundo mecanismo novo que alivia o CLAUDE.md é a memória automática. A ideia é que agora o Claude se lembra não apenas do que escreveu, mas também do que descobriu por si próprio. Um guia separado, «Memória do Claude vs. CLAUDE.md», explica em que difere o seu funcionamento do CLAUDE.md.

A diferença entre os dois tipos de memória:

Funciona assim: enquanto trabalha na sua tarefa, o Claude deteta detalhes úteis — que comando executa a compilação, onde a depuração encontrou um obstáculo, o que lhe pediu para fazer de maneira diferente — e guarda-os nas suas notas. Recupera-os na sessão seguinte. Importante: guarda-os de forma seletiva, mantendo apenas aquilo que considera útil para o futuro.

As notas ficam numa pasta separada para cada projeto, com um ficheiro de índice chamado MEMORY.md. Pode vê-las e editá-las com o comando /memory. São ficheiros de texto comuns, por isso pode lê-las, editá-las ou eliminá-las em qualquer momento.

Na prática, isto significa que agora o Claude regista algumas das coisas que antes acrescentava pessoalmente ao CLAUDE.md depois de cada erro. Assim, o seu ficheiro de regras fica ainda mais curto — o que é bom.

Porque é que o Opus 5 contesta as suas instruções?#

Há também um reverso da medalha.

Um modelo a quem é dado o direito de usar o discernimento irá, por definição, por vezes discordar de um comando rígido se encontrar uma opção melhor no contexto.

O que isto significa para si se atualizou para o Opus 5 e algo correr mal:

1. Reveja as competências e os plugins antigos. As configurações criadas para modelos anteriores podem entrar em conflito com a nova lógica. Vale a pena voltar a testar algo que antes funcionava como um relógio.
2. Remova as formulações mais rígidas. Os modelos de quinta geração lidam pior com comandos como «nunca faças X, faz sempre apenas Y» do que com formulações flexíveis que expliquem porquê.
3. Esteja atento aos casos em que o modelo para demasiado cedo. Por vezes, isso indica que uma instrução se contradiz ou colide com uma regra de um CLAUDE.md demasiado extenso.

Como reescrever o CLAUDE.md para o Opus 5: passo a passo#

Eis o processo para trabalhar com um CLAUDE.md herdado de modelos anteriores.

1. Execute a verificação integrada

   Escreva claude doctor no projeto. A ferramenta irá sugerir o que remover do ficheiro demasiado extenso e o que manter.

2. Remova o que é óbvio

   Apague todas as linhas que o Claude consegue inferir a partir do próprio código: estrutura de pastas, lista de bibliotecas e frases gerais como «escreva código limpo».

3. Elimine as contradições

   Percorra o ficheiro do início ao fim e encontre regras incompatíveis. Mantenha uma e elimine a regra que entra em conflito com ela.

4. Passe os procedimentos para competências

   Passe para uma competência separada tudo o que se tenha transformado de facto num conjunto de instruções passo a passo. Deixe uma ligação de uma linha no CLAUDE.md.

5. Torne específicas as regras restantes

   Reformule cada regra para que possa ser verificada: «formate corretamente» passa a «use uma indentação de 2 espaços».

6. Ative a memória automática e verifique a extensão

   Certifique-se de que a memória automática está a funcionar (/memory) e de que o ficheiro tem menos de 200 linhas. Caso contrário, ainda há algo a passar para outro lado.

Para não fazer a primeira revisão manualmente, peça ao Claude que a faça. Eis um prompt que pode usar como ponto de partida — copie-o e cole-o numa sessão aberta no seu projeto:

Lê o meu CLAUDE.md e o meu código. A tua tarefa é tornar o CLAUDE.md mais curto e útil para um modelo de quinta geração.

Analisa o ficheiro e divide todas as regras em três grupos:

MANTER - problemas específicos do projeto e convenções que não consegues inferir por ti a partir do código.

ELIMINAR - coisas óbvias que já sabes e tudo o que pode ser inferido a partir do código.

MOVER PARA UMA COMPETÊNCIA - procedimentos com várias etapas que atualmente estão no CLAUDE.md sob a forma de texto.

No grupo 1, reformula as regras vagas para que sejam concretas e verificáveis.
Encontra as regras contraditórias e apresenta-as separadamente.
Devolve uma nova versão do CLAUDE.md com menos de 200 linhas, juntamente com uma lista do que propões mover para competências.
Não alteres nenhum ficheiro até eu confirmar.

Repare na última linha: «Não alteres nada até eu confirmar.» Isto é importante com um modelo que agora usa o seu discernimento: peça-lhe primeiro que apresente um plano e deixe a decisão consigo.

Porque é que o contexto é mais importante do que o prompt?#

Se deixar de lado os pormenores sobre o Opus 5 e olhar para o quadro geral, toda esta análise trata de uma ideia: o contexto é mais importante do que o prompt. O trabalho mais importante acontece antes do pedido — quando prepara o ambiente em que o modelo irá trabalhar.

CLAUDE.md, competências e memória automática fazem todos parte da mesma coisa: aquilo que o Claude vê antes da sua primeira mensagem. Pode ajustar indefinidamente a formulação do pedido, mas, se o contexto estiver mal preparado — um CLAUDE.md demasiado extenso, regras contraditórias, falta de estrutura —, os resultados continuarão a ser inconsistentes.

Uma verificação simples: sem um primeiro cérebro, um segundo cérebro não ajudará. Neste artigo, «segundo cérebro» refere-se à estrutura de conhecimento sobre um projeto que o modelo consulta em cada pedido. Mas só funciona quando assenta numa compreensão clara da tarefa da sua parte. Uma ferramenta amplifica o seu pensamento, e é aí que termina o seu papel.

A atualização do Opus 5 tornou esta lógica mais clara. A Anthropic mostrou, com o seu próprio trabalho, que, quando o modelo é suficientemente inteligente, as regras adicionais só prejudicam e a vantagem cabe a quem preparou cuidadosamente o contexto. Esta competência continuará a ser útil em todos os modelos seguintes, seja o Opus 6 ou qualquer outro.

Por onde deve começar agora?#

Não deixe para «um dia destes». O primeiro passo mais simples é abrir o CLAUDE.md agora mesmo e perguntar honestamente a si próprio, linha a linha: isto é um problema que o Claude não consegue inferir ou é algo óbvio que acrescentei por precaução? Tudo o que estiver no segundo grupo pode ser eliminado.

Depois, passe o ficheiro pelo prompt da secção anterior, passe os procedimentos longos para competências e confirme que a memória automática está ativada. Uma noite de trabalho e o seu contexto tornar-se-á uma base concisa e precisa para o modelo.

Pode aplicar isto num projeto real seu: CLAUDE.md, um segundo cérebro e competências para as suas tarefas.

Conheça o Ailoot.