# CLAUDE.md depois do Opus 5: porque as instruções longas atrapalham agora o Claude
> O Claude Opus 5 é mais inteligente, e as regras antigas e extensas no CLAUDE.md atrapalham-no. O que manter, o que passar para competências e como ativar a memória automática. Inclui um prompt pronto a usar.
Source: https://ailoot.ai/blog/pt-pt/claude-md-after-opus-5/
Canonical: https://ailoot.ai/blog/pt-pt/claude-md-after-opus-5/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-063
Revision: sha256-c2be9093a3fec3f04c2c455ed929a0eb62e793e55e787e43cbbdb24303a18be7
Principal conclusão
O Claude Opus 5 foi lançado a 24 de julho de 2026 e, com ele, a Anthropic fez algo contraintuitivo: removeu mais de 80% das instruções do prompt de sistema do Claude Code. A ideia é simples: o modelo tornou-se mais inteligente e as regras rígidas adicionais agora atrapalham-no. O mesmo se aplica ao seu CLAUDE.md. Vou explicar o que remover, o que passar para competências e como ativar a memória automática para que o Claude volte a seguir melhor as instruções.
Encontrará informações sobre como trabalhar com o Ailoot na [documentação](https://ailoot.ai/docs/).
## O que mudou no Claude após o lançamento do Opus 5?
Principal conclusão
Com o Opus 5, a Anthropic mudou a sua abordagem às instruções dadas ao modelo. O Claude Code costumava ter um enorme prompt de sistema com centenas de regras. Na nova versão, foi reduzido em mais de 80% — e a qualidade da programação não diminuiu. A razão: os modelos de quinta geração são suficientemente inteligentes para tomar decisões com base no contexto. Já não precisam de uma lista rígida de comandos.
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?»](https://ailoot.ai/blog/pt-pt/claude-opus-5-review/). 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:
Removemos mais de 80% do prompt de sistema do Claude Code — e não observámos uma descida perceptível da qualidade nas tarefas de programação. Estávamos a limitar demasiado o Claude.
— Anthropic, https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models
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?
Principal conclusão
O CLAUDE.md é carregado para o contexto no início de cada sessão e consome tokens tal como a conversa. A documentação oficial do Claude Code recomenda que o ficheiro tenha menos de 200 linhas, porque os ficheiros mais longos ocupam mais contexto e reduzem o cumprimento das instruções. Além disso, quando duas regras se contradizem, o Claude escolhe uma ao acaso. Um CLAUDE.md demasiado extenso acrescenta ruído e dificulta que o modelo se mantenha no rumo certo.
É 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»](https://ailoot.ai/blog/pt-pt/claude-md-template/), 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:
Mantenha os ficheiros dentro do limite de 200 linhas. Os ficheiros mais longos consomem mais contexto e reduzem o cumprimento das instruções.
— Documentação do Claude Code, https://code.claude.com/docs/en/memory
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:
| | Antes (modelos mais fracos) | Agora (Opus 5 e modelos de quinta geração) |
|----|----|----|
| Lógica | Mais regras significam resultados mais fiáveis | Menos regras significam maior cumprimento |
| CLAUDE.md | Uma lista longa para todas as situações | Curto: só o que o modelo não consegue inferir por si |
| Instruções | Comandos rígidos: «faz assim» | Confie no discernimento do modelo |
| Regras repetidas | Repita-as para garantir a fiabilidade | A repetição só atrapalha |
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?
Principal conclusão
Mantenha no CLAUDE.md apenas aquilo que o Claude não consegue inferir a partir do próprio código: problemas específicos do projeto, convenções não óbvias, comandos de compilação e convenções que diferem das predefinições. Remova tudo o que for óbvio e que o modelo já saiba, bem como tudo o que possa ler diretamente no código. A regra da documentação é: acrescente uma linha quando o Claude cometer o mesmo erro pela segunda vez. Não antes, nem por precaução.
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:
| Vaga (não acerta) | Específica (acerta) |
|----|----|
| Formate o código corretamente | Use uma indentação de 2 espaços |
| Teste as alterações | Execute `npm test` antes de fazer commit |
| Mantenha os ficheiros organizados | Os handlers de API ficam em `src/api/handlers/` |
| Escreva boas mensagens de commit | Comece a mensagem de commit com um tipo: `fix:`, `feat:` |
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.
Sugestão
Um teste rápido para cada linha do CLAUDE.md: «Será que o Claude consegue descobrir isto por si só, apenas olhando para o meu código?» Se sim, apague-a. Mantenha apenas o que não pode ser inferido a partir do próprio projeto.
## Para onde deve passar as regras que não cabem no CLAUDE.md?
Principal conclusão
Tudo o que, no CLAUDE.md, deixou de ser um facto simples e se transformou num procedimento com várias etapas deve ser passado para uma competência. Uma competência é um ficheiro de instruções separado que só é carregado quando é realmente necessário. No resto do tempo, não ocupa contexto. Assim, uma instrução longa praticamente não tem custo até ser chamada. Isto é divulgação progressiva — carregar informação conforme necessário, por partes, precisamente quando é necessária.
É 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»](https://ailoot.ai/blog/pt-pt/choose-claude-code-skills/), 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:
Ao contrário do conteúdo do CLAUDE.md, o corpo de uma competência só é carregado quando é utilizada — por isso, o material de referência extenso praticamente não tem custo até ser necessário.
— Documentação do Claude Code, https://code.claude.com/docs/en/skills
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?
Principal conclusão
A memória automática permite que o Claude registe por iniciativa própria coisas que vale a pena recordar: comandos de compilação, descobertas de depuração, as suas preferências e correções. Antes, tinha de acrescentá-las manualmente ao CLAUDE.md. Agora, o Claude mantém as suas próprias notas, separadas das suas regras, e recupera-as em sessões posteriores. A memória automática está ativada por predefinição nos modelos de quinta geração.
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»](https://ailoot.ai/blog/pt-pt/claude-memory-claude-md-auto-memory/), explica em que difere o seu funcionamento do CLAUDE.md.
A diferença entre os dois tipos de memória:
| | CLAUDE.md | Memória automática |
|----|----|----|
| Quem a escreve | Você | O próprio Claude |
| O que contém | Instruções e regras | Descobertas e padrões |
| Exemplo | «Indentação de 2 espaços» | «A compilação falha se o Redis não estiver em execução» |
| Quando é atualizada | Edita-a manualmente | O Claude atualiza-a enquanto trabalha |
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.
Nota
A memória automática guarda as notas localmente. As notas selecionadas são carregadas no contexto do Claude e enviadas ao serviço de modelos configurado; armazenamento local não significa processamento offline. A retenção e o treino dependem do serviço e das definições da conta. Use `/memory` para inspecionar as notas e mantenha segredos fora delas.
## Porque é que o Opus 5 contesta as suas instruções?
Principal conclusão
O Opus 5 é suficientemente inteligente para, por vezes, discordar de uma instrução rígida se encontrar uma opção melhor no contexto. Para quem tem competências e plugins configurados para modelos anteriores, isto pode parecer que «o modelo se tornou indisciplinado». Na realidade, simplesmente deixou de seguir cegamente comandos que considera subótimos. Vale a pena rever as configurações antigas antes de mudar.
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.
Aviso
Se uma competência conhecida começar subitamente a comportar-se de forma estranha depois de mudar para o Opus 5, a instrução antiga que contém é mais frequentemente a culpada do que o próprio modelo. Faça-lhe a mesma limpeza que ao CLAUDE.md: remova o que for óbvio e as contradições e mantenha apenas as especificidades.
## Como reescrever o CLAUDE.md para o Opus 5: passo a passo
Principal conclusão
A limpeza do CLAUDE.md demora uma noite. Primeiro, execute a verificação integrada; depois, remova manualmente o que for óbvio e as contradições, passe os procedimentos longos para competências, ative a memória automática e mantenha apenas os problemas específicos do projeto. Abaixo estão os passos e um prompt pronto a usar para fazer a primeira revisão por si.
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:
Prompt: Limpar um CLAUDE.md demasiado extenso
```
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?
Principal conclusão
A formulação do seu pedido importa menos do que as pessoas pensam. Muito mais importante é aquilo que o modelo vê antes do pedido: a estrutura do projeto, as regras, a memória e as competências. Isto é engenharia de contexto — trabalhar com o contexto como principal competência de quem faz vibe coding. A atualização do Opus 5 apenas reforça esta lógica: quanto mais inteligente for o modelo, mais importante é o ambiente em que o coloca. Em comparação, a formulação do pedido é secundária.
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?
Principal conclusão
Abra o seu CLAUDE.md e analise-o à luz do novo princípio: é uma nota curta sobre problemas específicos do projeto e nada mais. Passe-o pelo prompt pronto a usar acima, passe os procedimentos para competências e ative a memória automática. Vai demorar uma noite e, depois disso, o Claude seguirá as suas instruções visivelmente melhor.
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.
### Fontes
- [Anthropic - As novas regras da engenharia de contexto para modelos Claude de quinta geração](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models)
- [Claude Code Docs - Memória e CLAUDE.md](https://code.claude.com/docs/en/memory)
- [Claude Code Docs - Competências (Agent Skills)](https://code.claude.com/docs/en/skills)
- [Claude Code v2.1.219 - notas de lançamento](https://github.com/anthropics/claude-code/releases/tag/v2.1.219)
Conheça o [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Quando deve uma secção do CLAUDE.md passar a skill?
Transfira-a quando um facto curto do projeto se tornar um procedimento com várias etapas, necessário apenas em certas tarefas. Mantenha uma referência concisa e as convenções estáveis do projeto no CLAUDE.md.
### A memória automática local significa que o conteúdo nunca chega a um serviço de modelos?
Não. Os ficheiros persistem localmente, mas as notas selecionadas entram no contexto do modelo. Inspecione-as com `/memory`, exclua segredos e verifique os controlos de dados do serviço configurado.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.