Respostas
Seu CLAUDE.md passou de uma página. O que sai dele?
A recomendação de manter o CLAUDE.md em menos de uma página é boa, e o motivo de ela ser difícil de seguir é que dois tipos diferentes de conhecimento acabam no mesmo arquivo. Um pertence ali para sempre: os comandos, as convenções, os erros que a IA repete nesta base de código. O outro é o que uma pessoa decidiu — qual regra está em vigor, por que um caminho foi abandonado, o que pode ser prometido a um cliente — e ele cresce sem limite, porque decisão nunca para de ser tomada. O corte não é entre importante e supérfluo. É entre o que pertence ao repositório e o que pertence ao time.
O que merece estar no arquivo
Fica o que a IA precisa para trabalhar nesta base de código e em nenhuma outra: como construir e testar, as convenções que o código realmente segue, o formato das pastas, e os erros específicos que a IA repete aqui. Esse conteúdo é estável, pertence ao repositório e é curto por natureza — para de crescer assim que está correto. Quando muda, muda porque o código mudou, e aí o mesmo commit que mexe no código mexe no arquivo.
O que está deixando o arquivo longo
Tudo que tem uma pessoa por trás. A decisão sobre preço ou escopo, a regra do que pode ser mandado para um cliente, o caminho que o time tentou e abandonou, a convenção combinada numa reunião por alguém que não commita. Cada linha merece ser guardada e nenhuma pertence ao repositório, então o arquivo cresce na única direção que ele não pode bancar — e no instante em que passa da página, o que mais importa passa a competir por atenção com o que só nunca foi apagado.
Para onde vai o segundo tipo
Para memória curada: escrita por pessoas e pelas IAs que elas usam, sancionada por gente antes de governar qualquer coisa, com uma condição de morte explícita, e ranqueada contra a tarefa em vez de carregada inteira. O problema de tamanho deixa de ser um problema de tamanho, porque a leitura SELECIONA. Arquivo não seleciona — ele é texto colocado diante do modelo, todo ele, toda vez, e o único jeito de mantê-lo pequeno é continuar apagando coisa de que alguém ainda precisa.
Como isso aparece na prática
O arquivo de contexto de um time chega a quatro páginas. Alguém corta de volta para uma, e o corte é feito por TAMANHO em vez de por dono: os comandos de build ficam porque são curtos, e o parágrafo explicando por que o time parou de usar uma biblioteca sai porque é longo. Duas semanas depois, uma IA propõe aquela biblioteca. O corte foi feito exatamente como se recomenda, e tirou justamente a linha que mais trabalhava.
Perguntas que as pessoas fazem sobre isso
- Então o CLAUDE.md está errado?
- Não. O arquivo está certo para o que pertence ao repositório, e o próprio repositório do Arroway mantém um exatamente para isso. O que ele não consegue fazer é guardar o que muda sem o código mudar, dizer que uma linha foi substituída, e alcançar quem nunca abre o repositório. São essas três lacunas que o segundo tipo preenche — e o arquivo para de crescer porque o crescimento passou a ter outro lugar.
- Não dá para só quebrar em vários arquivos?
- Dá, e isso adia o problema em vez de resolver. Mais arquivos significa mais texto diante do modelo, ou uma regra de carregamento que alguém tem que manter — e nenhum dos dois toca no que de fato dói: nada dentro de um arquivo diz qual de duas linhas que se contradizem é a que vale hoje. Quebrar organiza o texto; não dá a uma decisão vigência, autoria, nem alguém que a aprovou.
- O que a IA lê, então, e como eu sei que chegou?
- Ela lê o arquivo para o que pertence ao repositório e chama o commons para o que pertence ao time, no começo do trabalho. Essa leitura é ranqueada contra a tarefa que ela declara e volta dizendo o orçamento que usou e o que não coube — então a pergunta "a IA recebeu mesmo as nossas regras?" passa a ter uma resposta que se olha, que é algo que arquivo nenhum oferece sobre si mesmo.
Onde isto se confere
A documentação do produto neste site (Como funciona, Instalação) e a spec sancionada no repositório. A recomendação de manter o arquivo de contexto curto é prática publicada; toda propriedade citada aqui sobre um arquivo de contexto comum é de qualquer arquivo de texto versionado — sem vigência, sem etapa de sanção, sem seleção, sem recibo de entrega. Esta página não afirma nada sobre a memória nativa de nenhum produto de IA.
https://www.arroway.app/pt-BR/answers/context-file-outgrew-a-page