Seguindo o exemplo dos Engenheiros da Anthropic.
A maioria dos arquivos CLAUDE.md se enquadra em um de dois modos de falha. Ou estão vazios, uma oportunidade perdida ocupando espaço na raiz de um projeto sem fazer nada. Ou estão inchados, com centenas de linhas que Claude nunca lê de fato, porque um arquivo tão grande é lido superficialmente, não absorvido.
As próprias equipes de engenharia da Anthropic não fazem nenhuma das duas coisas. Seus arquivos CLAUDE.md internos são curtos, impiedosamente eliminados e tratados menos como documentação e mais como notas de integração para um funcionário brilhante, porém genuinamente novo, que não se lembra de nada do dia anterior. Essa abordagem, diretamente das diretrizes da própria Anthropic, é a chave para entender por que a maioria dos arquivos CLAUDE.md falha e o que realmente resolve o problema.
Este é o guia completo e prático, baseado na documentação oficial da Anthropic, no blog de engenharia deles e nos padrões que aparecem consistentemente em equipes que realmente trabalharam seriamente nisso, para escrever um arquivo CLAUDE.md que Claude realmente segue em vez de apenas folhear.
O que CLAUDE.md realmente é e por que seu tamanho o prejudica.
O arquivo CLAUDE.md é o primeiro que o Claude Code lê, automaticamente, no início de cada sessão. Não apenas uma vez. Em todas as sessões, sempre, independentemente da tarefa específica.
Esse simples fato é a razão pela qual o tamanho é a variável mais importante para o funcionamento de um arquivo CLAUDE.md. A própria documentação oficial de boas práticas da Anthropic é explícita: mantenha-o conciso, com o objetivo de ter menos de 200 linhas, sendo que algumas das equipes mais disciplinadas chegam a usar apenas 60. O limite máximo absoluto, antes que o Claude comece a perder a qualidade em meio ao ruído, gira em torno de 300 linhas.
Para entender por que isso importa, é preciso compreender com o que o arquivo está realmente competindo. Cada linha em CLAUDE.md consome contexto que poderia ser direcionado para a tarefa em si e, mais importante, cada linha dilui a relação sinal-ruído das instruções que realmente importam. Um arquivo com 40 linhas de orientação universalmente relevante é seguido atentamente. Um arquivo com 400 linhas, das quais 40 são relevantes e 360 são casos extremos que afetam talvez uma em cada vinte tarefas, é parcialmente ignorado, porque o modelo não consegue determinar com precisão quais das 40 linhas são as que realmente se aplicam no momento.
É por isso que o modo de falha de arquivo vazio é tão real quanto o de arquivo inchado. A ausência de um arquivo CLAUDE.md significa que o Claude inicia cada sessão sem nenhum contexto sobre sua base de código específica, suas convenções, suas preferências reais, tendo que reinventar a roda ou adivinhar informações que um arquivo de trinta segundos poderia ter fornecido de forma clara.
A regra que corrige ambos os modos de falha: aplicabilidade universal
O único teste que diferencia uma boa linha do CLAUDE.md de uma ruim, seguindo o padrão adotado pelas próprias equipes da Anthropic, é o seguinte: como esse arquivo é carregado em todas as sessões, independentemente da tarefa, cada instrução nele precisa ser amplamente aplicável, e não situacional.
Uma regra como “ao criar um novo esquema de banco de dados, siga esta convenção de nomenclatura específica” não passa neste teste. Ela só é relevante durante a rara sessão que de fato aborda o design do esquema, e em todas as outras sessões, permanece em contexto sem fazer nada além de desviar a atenção das regras que realmente importam no momento.
Uma regra como “sempre execute o verificador de tipos após qualquer série de alterações de código” passa no teste, porque se aplica independentemente da tarefa específica em que Claude está trabalhando nesta sessão em particular.
A disciplina prática que isso cria é a seguinte: qualquer coisa específica, situacional ou relevante apenas para um subconjunto específico do trabalho pertence a um local diferente do arquivo raiz CLAUDE.md. O próprio formato de arquivo do Anthropic oferece suporte direto a isso por meio da sintaxe de importação. @caminho/para/import, permitindo dividir orientações específicas e situacionais em arquivos separados que só são utilizados quando a situação em questão realmente exige, em vez de estarem presentes no contexto de cada sessão por padrão.
A estrutura real que funciona
Com base no padrão que se repete consistentemente em equipes que seguem de perto as orientações da Anthropic, esta é a estrutura que se mostra eficaz na prática.
Visão geral do projeto, resumo.O que é este código-fonte, em duas ou três frases. Não precisa ser uma cópia completa do README, apenas o suficiente para que Claude entenda a estrutura básica do sistema.
Comandos que Claude precisa executar constantemente.Comando de compilação, comando de teste, comando de lint, esse punhado de coisas que surgem em praticamente todas as sessões, independentemente da tarefa específica. Nem todos os comandos que seu projeto suporta, mas sim aqueles que você realmente gostaria que fossem executados automaticamente.
Regras de estilo de código que são inegociáveis.Não se trata de um guia de estilo completo duplicado no arquivo, mas sim de um punhado de convenções específicas ou importantes o suficiente para que você corrigisse imediatamente um colaborador humano caso ele as aplicasse incorretamente.
Expectativas de teste.Quando os testes devem ser executados, o que “aprovado” realmente significa para este projeto e se um tipo específico de alteração requer um tipo específico de teste.
O que Claude nunca deveria fazer sem pedir permissão.Operações destrutivas, implantações, qualquer ação que afete dados de produção, pushes forçados, quaisquer que sejam as salvaguardas genuínas para esta base de código específica.
Importações para qualquer situação específica.Convenções de esquema de banco de dados, notas de arquitetura de um subsistema específico, procedimentos de implantação, qualquer coisa relevante para uma parte específica do trabalho, em vez de todas as sessões, obtida por meio de @caminho/para/importar em vez de embutido.
Observe o que está ausente desta lista. Um diagrama de arquitetura completo. Um guia de estilo completo. Documentação abrangente de cada módulo. Essas coisas têm valor real, mas não pertencem ao arquivo que é carregado em todas as sessões, independentemente da relevância.
Instruções de escrita que Claude realmente segue
A estrutura por si só não garante a adesão. A forma como você formula as instruções individuais é importante, e a própria prática interna da Anthropic oferece uma técnica específica e comprovada para isso.
Na Anthropic, as instruções são reforçadas com marcadores de ênfase explícitos, como “IMPORTANTE” ou “VOCÊ DEVE”, especificamente para melhorar o cumprimento das regras que realmente não podem ser ignoradas. Isso não é apenas um uso decorativo de maiúsculas. É um sinal deliberado de que esta linha em particular tem mais peso do que o texto ao redor, reservado para as poucas instruções em que um descumprimento realmente faz diferença.
# Testando
– IMPORTANTE: Sempre execute testes antes de confirmar as alterações.
– É OBRIGATÓRIO executar o verificador de tipos após qualquer série de alterações no código.
A disciplina que isso exige é a contenção. Se cada linha do seu CLAUDE.md estiver marcada como IMPORTANTE, nenhuma delas será, e o marcador de ênfase deixará de transmitir qualquer sinal real. Reserve-o especificamente para as regras em que o custo de Claude ignorá-las seja realmente alto, e não como um intensificador geral aplicado a tudo o que você prefere que seja seguido.
Use a estrutura Markdown da maneira como um leitor a escanearia.
Claude analisa um arquivo CLAUDE.md da mesma forma que um leitor humano, estruturalmente, não linearmente. Parágrafos densos e ininterruptos são mais difíceis de analisar com precisão do que seções com títulos claros e marcadores. Use cabeçalhos Markdown para agrupar instruções relacionadas e marcadores em vez de parágrafos sempre que o conteúdo for realmente uma lista de pontos distintos, em vez de um texto contínuo.
Essa é uma pequena mudança mecânica, mas que se acumula. Um arquivo organizado em seções claras — Comandos, Estilo, Testes, Regras de Segurança — permite que tanto Claude quanto qualquer pessoa que leia o arquivo localize rapidamente a seção relevante, em vez de precisar analisar um bloco inteiro de texto indiferenciado para encontrar a única regra importante para a tarefa em questão.
O padrão de divulgação progressiva
Este é o conceito arquitetônico mais importante para manter um arquivo CLAUDE.md curto e completo, e é um paralelo direto ao padrão que a Anthropic recomenda para escrever Skills.
A ideia: o arquivo raiz CLAUDE.md contém apenas o que é universalmente relevante. Tudo o que for mais específico, situacional ou profundo é movido para seu próprio arquivo e importado somente quando o contexto específico realmente o exigir.
## Documentos de referência
### Procedimento Operacional Padrão (POP) de SEO de Conteúdo — @docs/CONTENT-SEO-SOP.md
Leia quando: estiver criando ou editando qualquer página de conteúdo.
### Arquitetura de API — @docs/arquitetura-de-api.md
Leia quando: Adicionar ou modificar endpoints de API
Esse padrão é o que permite que um projeto realmente complexo e grande permaneça abaixo da meta de 200 linhas para seu arquivo raiz, sem perder a profundidade que o projeto realmente precisa. A profundidade ainda existe, apenas reside em arquivos que só entram em contexto quando relevantes, em vez de estarem presentes em todas as sessões por padrão, diluindo o sinal das regras que importam universalmente.
Especificamente para monorepos, isso se estende naturalmente a arquivos CLAUDE.md aninhados, um arquivo raiz com convenções universais e arquivos específicos de subdiretórios que são carregados somente quando Claude está realmente trabalhando naquela parte específica do código-fonte.
Auditoria e manutenção do seu CLAUDE.md ao longo do tempo
Um arquivo CLAUDE.md não é um artefato que pode ser gravado apenas uma vez. Ele se degrada da mesma forma que qualquer conjunto acumulado de instruções, por meio de adições que ninguém remove.
O padrão de falha específico que vale a pena observar: a maioria dos arquivos CLAUDE.md acumula instruções como “hotfixes”; um comportamento específico que Claude implementou incorretamente uma vez é adicionado como uma nova regra, e o arquivo cresce sem que ninguém verifique se as regras anteriores ainda são relevantes, corretas ou se agora são contraditas por algo adicionado posteriormente. Se duas regras no arquivo se contradizem, Claude pode resolver o conflito arbitrariamente, o que é um resultado pior do que se qualquer uma das regras fosse seguida consistentemente.
A prática concreta que isso exige é a revisão periódica do arquivo, incluindo arquivos de subdiretórios aninhados e quaisquer arquivos de regras importados, procurando especificamente por instruções desatualizadas, regras conflitantes e qualquer coisa que tenha sido introduzida e que não atenda ao teste de aplicabilidade universal realizado anteriormente. Se Claude já estiver fazendo algo corretamente sem uma instrução específica presente, essa é uma candidata à exclusão, não uma regra para ser mantida por precaução. Se uma linha em CLAUDE.md existe apenas por causa de um único incidente ocorrido meses atrás e que nunca mais se repetiu, vale a pena questionar se ela ainda justifica sua presença no contexto de todas as sessões.
As próprias ferramentas da Anthropic dão suporte direto a essa manutenção. Executar periodicamente um arquivo CLAUDE.md no Anthropic Prompt Improver é uma prática documentada para detectar exatamente esse tipo de desvio, frases que se tornaram confusas, instruções que não cumprem mais sua função original, regras que começaram a entrar em conflito silenciosamente com algo adicionado posteriormente.
Exemplo prático: antes e depois
Para tornar a diferença concreta, veja como um arquivo CLAUDE.md com especificações excessivas se compara ao arquivo do mesmo projeto após a aplicação dos princípios acima.
Antes, um padrão de falha comum. Duzentas e oitenta linhas. Uma visão geral completa da arquitetura, duplicada do README. Convenções detalhadas do esquema do banco de dados embutidas, relevantes para talvez uma sessão em cada quinze. Um guia de estilo completo, reproduzido do documento de estilo separado da equipe. Dez instruções diferentes para casos extremos, acumuladas uma a uma após incidentes específicos, várias das quais agora se contradizem ligeiramente em relação à formatação das mensagens de commit.
DepoisAplicando a disciplina acima. Quarenta linhas. Uma descrição do projeto em duas frases. Os quatro comandos realmente necessários constantemente: build, test, lint e typecheck. Cinco regras de estilo inegociáveis, aquelas específicas o suficiente para que um humano possa corrigi-las imediatamente. Uma expectativa clara de testes. Uma breve lista de coisas que nunca devem ser feitas sem perguntar. Uma linha de importação apontando para as convenções do esquema do banco de dados, agora em um arquivo próprio, carregado apenas quando uma sessão realmente interage com o esquema. As regras contraditórias de mensagens de commit, resolvidas excluindo a antiga e mantendo apenas o padrão atual.
A segunda versão é mais curta e mais completa, não menos. Nada de valor genuíno foi removido; o conteúdo foi realocado para onde pertence, sendo carregado apenas quando realmente relevante, em vez de estar presente no contexto de cada sessão, independentemente de a sessão abordar ou não o assunto.
A perspectiva que transforma a maneira como você escreve cada linha.
Antes de entrarmos em detalhes estruturais, vale a pena analisar o modelo mental específico recomendado pelas próprias diretrizes da Anthropic, pois ele altera o conteúdo do que você escreve, e não apenas o seu tamanho.
Imagine Claude como um funcionário brilhante, porém muito novo, com amnésia, que precisa de instruções explícitas. Cada palavra nessa descrição tem um propósito real. Brilhante significa que você não precisa explicar demais os fundamentos, pois a competência geral já está presente. Novo significa que ele não possui nenhum conhecimento institucional acumulado sobre o seu projeto específico, as convenções específicas da sua equipe, o histórico específico por trás da construção de algo daquela forma. Amnésia significa que, mesmo que uma sessão anterior tenha explicado algo, esta sessão começa do zero, e o arquivo CLAUDE.md é a única coisa que carrega esse contexto de forma confiável.
Essa estrutura explica diretamente por que a regra da aplicabilidade universal é tão importante. Você não entregaria a um novo funcionário, logo no primeiro dia, um manual de trezentas páginas cobrindo todos os casos extremos que a empresa já enfrentou e esperaria que ele internalizasse tudo antes da primeira tarefa. Você daria a ele o essencial para funcionar imediatamente e o direcionaria para documentação mais detalhada para as situações específicas em que se tornasse relevante. O CLAUDE.md é esse documento essencial para o primeiro dia, não a wiki completa da empresa.
Isso também explica por que a especificidade importa mais do que a maioria das pessoas inicialmente imagina. Um novo funcionário instruído a “escrever um bom código” não tem ideia do que isso realmente significa no seu contexto específico, bom segundo qual padrão, formatado de que maneira, testado em que nível. Um novo funcionário instruído a “executar o verificador de tipos após qualquer série de alterações no código e nunca confirmar alterações sem que os testes passem” recebe uma instrução concreta e acionável. A brilhante abordagem do “novo com amnésia” é uma constante e útil verificação contra a escrita de instruções vagas o suficiente para parecerem razoáveis, mas que na verdade não restringem o comportamento de forma específica.
Padrões de Monorepo e Multi-Projeto
Tudo o que foi dito acima pressupõe um projeto único e relativamente contido, mas os mesmos princípios se aplicam diretamente a estruturas de repositório maiores e mais complexas, e vale a pena explicitar como isso ocorre.
Para um monorepo contendo múltiplos serviços ou pacotes distintos, o padrão que funciona bem é um arquivo CLAUDE.md raiz contendo apenas o que é genuinamente universal em todo o repositório: ferramentas de compilação, convenções transversais e as poucas regras que se aplicam independentemente do pacote específico em que uma sessão está trabalhando. Cada pacote ou serviço individual recebe seu próprio arquivo CLAUDE.md, aninhado em seu próprio diretório, contendo as especificidades relevantes apenas para aquela parte do código.
Isso é importante porque o Claude Code lê os arquivos CLAUDE.md relevantes para o local onde está trabalhando, o que significa que uma sessão focada no pacote de frontend não precisa carregar convenções específicas do backend em seu contexto, e vice-versa. Acertar esse aninhamento costuma ser a diferença entre um monorepo onde o CLAUDE.md permanece realmente útil em grande escala e um onde o arquivo raiz se expande tentando abranger as especificidades de todos os pacotes em um único documento indiferenciado.
Um sinal prático de alerta de que sua estrutura de monorepo precisa dessa abordagem aninhada em vez de um único arquivo raiz gigante: se você notar que o arquivo raiz CLAUDE.md contém seções com escopo explícito, com expressões como “se estiver trabalhando no pacote de frontend” ou “relevante apenas para o serviço de API”, essa delimitação condicional é um forte indício de que essas seções pertencem a um arquivo aninhado específico para aquele pacote, e não ao arquivo que é carregado a cada sessão, independentemente do pacote que ela esteja acessando.
Escrever CLAUDE.md em equipe, não apenas individualmente
Em qualquer projeto com mais de uma pessoa trabalhando efetivamente com o Claude Code, o arquivo CLAUDE.md deixa de ser um arquivo de preferências pessoais e passa a ser uma infraestrutura compartilhada, o que altera algumas das considerações práticas relacionadas à sua manutenção.
Trate as alterações em CLAUDE.md com o mesmo rigor de revisão que você aplicaria a alterações em qualquer configuração compartilhada que afete o fluxo de trabalho de toda a equipe. Um colega que adiciona uma nova instrução de “correção rápida” após uma única sessão frustrante, sem qualquer revisão, é exatamente o mecanismo que produz os arquivos inchados e contraditórios descritos na seção de erros acima. Uma etapa de revisão simples, mesmo que seja apenas uma segunda pessoa dando uma olhada nas diferenças antes da mesclagem, detecta uma parcela significativa tanto do problema de inchaço quanto do problema de contradição antes que eles se acumulem.
Também é importante definir explicitamente quem é o responsável pelas auditorias periódicas do arquivo. Sem uma atribuição clara de responsabilidades, o trabalho de manutenção descrito anteriormente — como remover instruções desatualizadas, resolver contradições e verificar o teste de aplicabilidade universal — tende a ser negligenciado justamente por não ser uma tarefa específica de ninguém e não bloquear nenhuma tarefa imediata, como acontece com uma compilação com problemas. Atribuir essa responsabilidade explicitamente, mesmo que informalmente, como uma tarefa recorrente, costuma ser a prática mais eficaz para evitar que o arquivo CLAUDE.md compartilhado da equipe se degrade da mesma forma que a maioria dos documentos compartilhados sem responsável definido acaba se degradando.
Erros comuns que comprometem um arquivo que, de outra forma, seria bom.
Alguns erros específicos aparecem repetidamente, e vale a pena mencioná-los diretamente, já que cada um tem uma solução simples e específica.
Tratar o arquivo CLAUDE.md como um repositório para todos os comandos suportados pelo projeto.Apenas os poucos comandos usados constantemente devem estar aqui. Uma referência completa de comandos deve estar na documentação do projeto, que Claude pode consultar quando realmente necessário, e não pré-carregada em todas as sessões.
Escrever instruções específicas e situacionais diretamente no arquivo raiz, em vez de importá-las.Essa é a maneira mais comum pela qual um arquivo CLAUDE.md ultrapassa a meta de 200 linhas sem que ninguém perceba, acontecendo gradualmente, com uma adição aparentemente razoável de cada vez.
Acumulando instruções de correção de erros sem nunca precisar removê-las.Cada correção é adicionada. Quase nada é removido. Seis meses depois, o arquivo tem o dobro do tamanho necessário e metade dele trata de incidentes que nunca se repetiram.
Ignorar os marcadores de ênfase ou usá-los em excesso.Ou todas as instruções são lidas com o mesmo peso, o que significa que nada se destaca como genuinamente inegociável, ou todas as linhas são marcadas como IMPORTANTES, o que produz o mesmo problema por meio de um mecanismo diferente.
Nunca chegou a testar se Claude seguiu o arquivo conforme escrito.A única maneira realmente eficaz de saber se um arquivo CLAUDE.md está funcionando é executando sessões reais com ele e verificando se o comportamento do Claude corresponde às instruções. Um arquivo que parece fácil de ler, mas que nunca foi testado em situações reais de uso, é apenas um palpite, não uma ferramenta comprovada.
Verificar a conformidade, e não apenas escrever e esperar.
A seção sobre erros mencionada acima abordou isso brevemente, mas merece uma análise própria, porque a maioria das pessoas que escrevem um arquivo CLAUDE.md nunca verifica se ele realmente funciona.
As próprias práticas recomendadas da Anthropic para o Claude Code descrevem um padrão de escritor e revisor que se aplica diretamente aqui, e vale a pena adaptá-lo especificamente para o CLAUDE.md, e não apenas para a geração de código. Execute uma sessão do Claude Code com seu arquivo CLAUDE.md atual em uma tarefa real. Em seguida, separadamente, execute uma segunda sessão para revisar a transcrição da primeira sessão, comparando-a especificamente com as instruções do arquivo e verificando cada regra individualmente: foi seguida? Foi ignorada? Foi seguida de forma inconsistente em momentos semelhantes da sessão?
Isso produz algo genuinamente mais útil do que uma sensação subjetiva de se o arquivo parece bem escrito. Gera uma lista concreta de quais instruções específicas estão sendo efetivamente seguidas e quais estão sendo ignoradas, que é a única maneira confiável de saber se uma mudança de frase, um marcador de ênfase ou uma reestruturação realmente melhoraram a adesão, em vez de apenas alterar a forma como o arquivo é lido por um leitor superficial.
Para instruções marcadas como IMPORTANTE ou VOCÊ DEVE especificamente, essa verificação é crucial, já que essas são as regras que você afirma explicitamente que não podem ser ignoradas. Se uma revisão detectar que um desses marcadores está sendo ignorado, isso indica diretamente que a instrução precisa ser reformulada, movida para uma posição anterior no arquivo ou que realmente entra em conflito com alguma outra tarefa que Claude precisa priorizar na mesma sessão.
Executar esse tipo de verificação, mesmo que ocasionalmente, e não necessariamente após cada sessão, transforma a manutenção do CLAUDE.md de um exercício de tentativa e erro em algo mais próximo de uma prática de engenharia real, com evidências concretas sobre quais alterações são úteis e quais apenas aumentam o tamanho do arquivo sem torná-lo mais eficaz.
Configurar isto ou corrigir um arquivo existente esta semana
Se você está começando do zero, resista à tentação de escrever um arquivo abrangente na primeira versão. Comece com as quatro ou cinco coisas que você se vê explicando para o Claude em quase todas as sessões: o comando de compilação, a regra de estilo que você sempre precisa corrigir, a expectativa de teste. Envie esse arquivo curto e só adicione mais itens quando perceber que está repetindo a mesma correção em várias sessões, o que indica que algo precisa estar no CLAUDE.md em vez de ser explicado novamente a cada vez.
Se você estiver corrigindo um arquivo existente e muito grande, execute a auditoria descrita acima antes de adicionar qualquer coisa nova. Extraia tudo o que falhar no teste de aplicabilidade universal para arquivos importados. Exclua tudo o que o Claude já faz corretamente sem a presença da instrução. Resolva quaisquer contradições encontradas. Reduza o arquivo raiz para menos de 200 linhas antes de considerar o que mais, se houver algo, realmente precisa ser adicionado.
A verdadeira medida do sucesso não é o quão completo o seu arquivo CLAUDE.md parece. É se o comportamento de Claude, sessão após sessão, corresponde de fato ao que está descrito no arquivo, sem que você precise explicar novamente o que já achava ter documentado. Um arquivo curto que é seguido consistentemente é sempre melhor do que um arquivo longo que é consultado apenas superficialmente.
artigo original: https://x.com/cyrilXBT/status/2084505415065198916
