CLAUDE.md demasiado longo? O que cortar e para onde vai

Um CLAUDE.md é demasiado longo quando tem linhas sem as quais o agente não erraria. A documentação da Anthropic aponta para menos de 200 linhas por ficheiro CLAUDE.md; nós contamos palavras, porque as linhas escondem a densidade. No fim deste guia terá auditado o seu ficheiro linha a linha, dado um destino a cada linha cortada e configurado um único ficheiro que o Claude Code, o OpenCode e o Kimi Code leem.

Um ficheiro de instruções longo não é um problema de escrita. É um problema de arrumação: quase todas as linhas são verdadeiras, só estão no sítio errado. Uma linha fora do sítio custa contexto em todas as sessões e enterra as regras que importam. A Anthropic di-lo sem rodeios: ficheiros CLAUDE.md inchados fazem com que o Claude ignore as suas instruções reais (Anthropic, Best practices(abre num novo separador)).

Todos os exemplos usam a Mossbank, uma aplicação fictícia de agendamento para empresas de canalização e aquecimento. O ficheiro e os números são inventados; os orçamentos e as regras são os que usamos na Neomanex.

De que precisa antes de começar

Audite os ficheiros que carregam em conjunto, não aquele que por acaso tem aberto. O agente nunca vê um ficheiro sozinho: o Claude Code carrega todos os CLAUDE.md desde o topo do projeto até à pasta onde está a trabalhar, mais tudo o que importam.

Meça o que carrega de facto

Deixámos de contar linhas. Uma linha de tabela pode conter um parágrafo, por isso orçamentamos palavras e tratamos um ficheiro denso como um ficheiro longo.

O custo de um ficheiro são as suas palavras: dois ficheiros de 180 linhas podem estar muito longe um do outro, por isso o orçamento é definido em palavras para cada tipo de ficheiro e para tudo o que carrega em conjunto.

Execute wc -lw em cada ficheiro, some as palavras e divida as palavras pelas linhas. Acima de cerca de 15 palavras por linha, as células das tabelas tornaram-se parágrafos: divida a célula ou mova o conteúdo para fora.

O objetivo de linhas da Anthropic existe porque «ficheiros mais longos consomem mais contexto e reduzem a adesão» (Anthropic, Memory(abre num novo separador)). Os imports contam por inteiro: os ficheiros importados também carregam no arranque.

O ficheiro raiz da Mossbank tem 420 linhas e cerca de 9.600 palavras: 23 palavras por linha, muito acima do máximo absoluto de 1.800 palavras para a raiz de um projeto.

Aplique o teste de uma linha a cada linha

A pergunta de poda da Anthropic é a auditoria inteira: remover esta linha faria o Claude cometer um erro? A disciplina está em fazê-la a cada linha, incluindo as que escreveu na semana passada.

O que é um registo de cortes? Um registo de cortes é uma tabela com uma linha por cada linha ou bloco do ficheiro: a linha, se o agente erra alguma coisa sem ela, porquê, e para onde vai a linha.

Ficam duas linhas. A linha 2 só fica porque indica o ficheiro que a prova.

Dê um destino a cada linha cortada

Apagar é o último recurso, não o primeiro. A maior parte das linhas cortadas é conhecimento que pertence a um sítio que o agente só lê quando precisa.

Uma linha que falha o teste de uma linha vai para o primeiro destino cuja pergunta tem resposta sim: hook, passo de fluxo de trabalho, regra de pasta, skill, página de documentação ou apagar.

Faça as perguntas por esta ordem. O primeiro sim escolhe o destino.

O hook vem primeiro porque o ficheiro é só um conselho: a documentação da Anthropic diz que, para bloquear uma ação independentemente do que o Claude decida, se deve usar um hook PreToolUse. O nosso guia para impedir que o Claude Code apague os seus ficheiros constrói um, passo a passo. Uma regra de pasta no Claude Code é um ficheiro .claude/rules/ com frontmatter paths:, aqui a corresponder a migrations/**, ou um CLAUDE.md filho nessa pasta. Nós limitamos as nossas por caminho.

A checklist de release da Mossbank é o exemplo clássico de linha mal arrumada: uma ordem e a aprovação da Dana, lidas por inteiro em todas as sessões, com a paragem entregue à memória. Guardamos processos deste tipo como fluxos de trabalho no ConvOps(abre num novo separador), para que o agente leia um passo de cada vez e a aprovação seja um passo próprio (como gerimos a nossa empresa com fluxos de trabalho). Tire todos os processos do ficheiro e ele encolhe até ser um ficheiro de identidade: é o caminho radical, o graph engineering (engenharia de grafos).

Mova cada linha e deixe um apontador de uma linha

Um corte que perde conhecimento não é um corte. É um bug futuro, por isso cada linha movida deixa um apontador para trás.

O CLAUDE.md de 420 linhas da Mossbank mantém as linhas que evitam erros e move todas as outras para um destino de onde só carregam quando são precisas.

O mapa de módulos da Mossbank passa a ser docs/module-map.md, e o ficheiro mantém uma linha que indica a página. Das 420 linhas, 90 ficam, 150 vão para três páginas de documentação, 60 para duas skills, 30 para uma regra de pasta, 25 para o fluxo de trabalho de release, 10 para dois hooks, e 55 são apagadas. O ficheiro acaba com cerca de 100 linhas, as 90 que ficaram mais 10 linhas de apontadores, e 1.100 palavras, abaixo do objetivo de 1.200 palavras.

Um import com @ não é um corte. @docs/module-map.md carrega a página no arranque na mesma. Um apontador simples não carrega nada até o agente o seguir.

Faça com que um só ficheiro sirva de CLAUDE.md e AGENTS.md

Ter dois ficheiros de instruções para três ferramentas significa que cada ferramenta lê um ficheiro diferente. Nós mantemos uma fonte e ligamos o outro nome a ela.

Com dois ficheiros, o Claude Code lê o CLAUDE.md enquanto o OpenCode e o Kimi Code leem o AGENTS.md; com o AGENTS.md como symlink para o CLAUDE.md, as três leem o mesmo ficheiro uma só vez (testado em outubro de 2026).

Testámos cada configuração a 9 de outubro de 2026, com uma palavra-código diferente em cada ficheiro:

Dois ficheiros separados divergem, e cada ferramenta segue instruções diferentes. Só o CLAUDE.md deixa o Kimi Code sem nada. Mantenha o CLAUDE.md como fonte e execute ln -s CLAUDE.md AGENTS.md: das quatro configurações que testámos, é a única em que as três ferramentas leem o mesmo texto uma só vez. O nosso é gerado: um script cria um AGENTS.md ao lado de cada CLAUDE.md, para que cada pasta tenha uma só fonte.

Segundo a documentação da Anthropic, as ferramentas Edit e Write do Claude Code recusam escrever através de um symlink, por isso edite o CLAUDE.md; em Windows, faça do CLAUDE.md um import de uma linha, @AGENTS.md. Apague ou mova os dois em conjunto: um CLAUDE.md apagado deixa a ligação AGENTS.md a apontar para nada.

Confirme que carregou e volte a verificar sempre que cresce

Um ficheiro aparado volta a crescer por defeito, porque cada lição quer viver no ficheiro que todos leem. A nova verificação faz parte da edição, não de um dia de limpezas.

O ficheiro da Mossbank ganha duas linhas na primeira semana, ambas lições reais, e a contagem de palavras deteta-as. A regra: uma lição nova vai primeiro para o seu destino, e só por último para o ficheiro.

Comece pelo seu processo mais longo. Crie uma conta gratuita no ConvOps(abre num novo separador), peça à sua IA que escreva esse processo como fluxo de trabalho e depois apague-o do ficheiro. Quer um segundo olhar sobre os ficheiros de instruções da sua equipa? Marque uma sessão de descoberta gratuita.

Erros comuns e as regras que deixaram

Cada regra do nosso orçamento existe porque um ficheiro errou alguma coisa, não porque um guia de estilo o mandou. Cada erro abaixo aconteceu connosco, recontado com a Mossbank.