17
kenimo49
6 min de leitura ·

O criador do CLAUDE.md escreve 2 linhas. A comunidade escreve 100. Quem está errado?

Boris Cherny, criador do Claude Code, mantém um CLAUDE.md pessoal de duas linhas. Você lê isso em uma entrevista e pensa: "ah, então o segredo é ser minimalista". Aí abre o seu repositório, encontra um CLAUDE.md de 187 linhas escrito por você mesmo, e fica com aquela sensação desconfortável de quem foi pego fazendo cosplay de engenheiro sênior.

A minha primeira reação foi apagar tudo e copiar o estilo do Boris. Testei em três projetos reais, com a versão de duas linhas e com a versão inchada. O resultado não foi nenhum dos dois extremos vencer limpo. Foi um detalhe sobre onde o contexto fica, que a leitura preguiçosa da entrevista do Boris esconde, e que a comunidade ignora quando posta print de CLAUDE.md gigante no X.

Esse post é o relato dos três experimentos e o que sobrou de regra no fim.

Duas barras: CLAUDE.md de 2 linhas e CLAUDE.md de 100 linhas, com setas mostrando onde cada um falha

As duas linhas do Boris, na íntegra

Antes de qualquer coisa, vou colocar o arquivo de duas linhas para você ver com seus próprios olhos. Não é folclore, é o que está publicado em entrevista.

# CLAUDE.md
- Habilitar automerge ao abrir um PR
- Postar no canal interno do Slack ao abrir um PR

Isso é tudo. Sem stack do projeto, sem convenções de código, sem estratégia de testes, sem comandos. Olha de novo. Duas linhas. E a pessoa que escreveu esse arquivo é a mesma que construiu o Claude Code.

A primeira leitura é: "ok, então CLAUDE.md deve ser pequeno". A leitura correta é mais chata: o CLAUDE.md pessoal do Boris é pequeno porque o CLAUDE.md compartilhado do time, na raiz do repositório do Claude Code, é atualizado várias vezes por semana e cobre todo o contexto do projeto. As duas linhas são as preferências individuais dele sobre uma base de conhecimento de time que já existe.

Quem copia o tamanho sem copiar a estrutura está copiando o sintoma, não a causa. Esse foi o erro do meu Experimento 1.

Experimento 1: 2 linhas em projeto solo

Peguei um projeto Next.js + TypeScript + Prisma que eu mantenho sozinho. Tinha um CLAUDE.md de 142 linhas. Apaguei tudo, deixei estas duas:

# CLAUDE.md
- Sempre rode `npm test` antes de PR
- Comente o código em português

A primeira semana foi uma série pequena de constrangimentos. O Claude reinventou as convenções de teste do projeto (Vitest, que ele teria sabido se o arquivo dissesse). Tentou abrir conexões diretas ao Prisma sem passar pelo client compartilhado. Sugeriu um middleware de auth no padrão de outro projeto meu. Tudo isso eu corrigia manualmente, e cada correção custava 30-60 segundos.

A média de "tempo perdido por sessão consertando o Claude" subiu para uns 4 minutos. Não parece muito, mas eu rodo umas 8 sessões por dia. Faz a conta: meia hora perdida por dia. Multiplicado por 30 dias úteis, é um dia de trabalho jogado fora por mês, em troca de um arquivo bonito de duas linhas.

Conclusão do Experimento 1: copiar o tamanho do Boris em projeto solo, sem ter o "CLAUDE.md compartilhado do time" que cobre o resto, é otimização performática. O arquivo fica bonito, o trabalho fica feio.

Experimento 2: 100+ linhas em projeto solo

Voltei para a versão inchada e levei o experimento ao extremo oposto. Subi o CLAUDE.md para 247 linhas. Coloquei convenções de código, padrões de teste, regras de migração de banco, política de tratamento de erros, exemplos de uso de cada lib do projeto, lista de pegadinhas que eu lembrei na hora.

Funcionou melhor que as três linhas. Não foi nem perto. Mas apareceu um efeito que eu não esperava: o Claude começou a ignorar instruções enterradas no meio do arquivo. Sabe a parte sobre "sempre passar pelo db-client.ts"? Estava na linha 138. O Claude voltou a fazer conexões diretas ao Prisma.

LLMs dão mais peso ao começo e ao fim da entrada. Uma instrução crítica enterrada no meio de um CLAUDE.md de 247 linhas tem chance real de ser ignorada. Não é bug, é como o modelo funciona.

Outra coisa: instruções contraditórias começaram a se acumular. Eu tinha uma linha antiga que dizia "use Jest" (do tempo em que era Jest) e uma linha nova "migramos para Vitest". As duas estavam no arquivo. O Claude às vezes seguia uma, às vezes a outra. CLAUDE.md inchado vira sedimento geológico: cada erro vira uma camada nova, ninguém limpa as camadas velhas.

Conclusão do Experimento 2: 247 linhas funciona melhor que 3, mas começa a ter custos próprios: instruções enterradas, contradições acumuladas, janela de contexto comida.

Experimento 3: o que de fato sobrou

A versão que ficou rodando no meu projeto solo tem 67 linhas. Não escolhi esse número por estética; foi o ponto onde parei de adicionar e comecei a podar. A estrutura é esta:

# CLAUDE.md

## ⚠️ Regras críticas (topo, sempre lidas)
- Nunca conectar direto ao Prisma. Use `lib/db-client.ts`
- Nunca commitar `.env`. Sempre atualizar `.env.example`
- Migrações destrutivas: pedir confirmação antes

## Visão Geral
E-commerce Next.js 14 App Router + TypeScript + Prisma + PostgreSQL.

## Comandos
- `npm run dev`, `npm test`, `npm run build`
- `npx prisma generate` quando schema mudar

## Pegadinhas (Se → Então)
- Se: nova rota API → Então: atualizar tipos em `src/lib/api-client.ts`
- Se: nova variável env → Então: atualizar `.env.example` + README

## Referências
- Spec API detalhada: `docs/api-spec.md`
- Estratégia de testes: `docs/testing.md`
- Procedimentos deploy: `docs/deploy.md`

Três coisas mudaram em relação à versão de 247 linhas. As regras críticas subiram para o topo, onde o modelo presta mais atenção. Os detalhes saíram do CLAUDE.md e foram para arquivos em docs/, referenciados por nome. E o estilo de código (indentação, ponto e vírgula, aspas) saiu do CLAUDE.md inteiro porque isso é trabalho do prettier, não do CLAUDE.md.

Esse último ponto é o que o Boris diria se você perguntasse: "não brigue com o modelo, e não escreva no CLAUDE.md o que o linter já garante". Estilo de código é regra determinística, joga no .prettierrc. CLAUDE.md é para o que precisa de julgamento.

Os três CLAUDE.md públicos que eu li

Antes de fechar, fiz a tarefa que faltava: olhei CLAUDE.md de repositórios públicos sérios para ver os números reais. Não vou postar diff por respeito a quem mantém, mas o resumo serve.

RepositórioLinhas do CLAUDE.md raizEstilo
Repositório do próprio Claude Code (time interno)atualizado várias vezes/semanagrande, vivo
Repositórios de framework AI populares80-200médio, estruturado
Repositórios indie pequenos no GitHub20-80enxuto

O padrão não é "minimalismo vence" nem "completude vence". O padrão é que o tamanho corresponde à quantidade de contexto que o time precisa compartilhar. Time interno do Claude Code: muito contexto, arquivo grande e vivo. Framework popular: contexto médio, arquivo médio. Projeto indie: pouco contexto, arquivo pequeno.

As duas linhas do Boris não são o padrão do time dele. São o delta pessoal dele sobre um padrão de time muito maior. Quem mostra o screenshot das duas linhas sem mostrar o resto está mostrando a ponta do iceberg como se fosse o iceberg.

A regra que sobrou

Depois dos três experimentos, a regra que ficou rodando é simples e nada glamorosa:

  • Em projeto solo: 50-80 linhas. Regras críticas no topo. Detalhes em docs/.
  • Em projeto de time: o CLAUDE.md da raiz cresce com o time. CLAUDE.md pessoal (em claude.local.md, no gitignore) fica pequeno como o do Boris.
  • Sempre: estilo de código sai do CLAUDE.md. Vai para o linter. Você só escreve o que precisa de julgamento.

Ninguém está errado entre "2 linhas" e "100 linhas". As duas estão respondendo perguntas diferentes. A pergunta certa é "qual é o contexto que precisa estar em algum lugar para o Claude trabalhar bem no meu projeto?". Esse contexto existe; a questão é se você o escreveu, e onde.

O CLAUDE.md de duas linhas é uma boa provocação. Não é um template.

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews

Carregando publicação patrocinada...
7

Meus 2 cents,

Parabens pelo post !

Alguns detalhes que faco no meu harness:

  • O LLM se perde no "meio" do contexto: para quem ainda nao viu isso, eh um fenomeno bem conhecido chamado "Lost in the Middle". Como citado no post, coloque regras importantes no inicio e objetivos no final - ajuda (mas nao resolve 100%)

  • Nao existe prompt "ative o Mega Brain master blaster constructor": em suma, nao adianta encher linguica, CLAUDE.md/AGENTS.md e skills sao prompts e somam na janela de contexto. Um bom prompt tem de carregar o contexto de tal forma que o LLM consiga escolher o proximo token com perfeicao - so isso. Nao tem "hocus pocus" secreto - eh apenas guiar o LLM para que ele gere tokens bons e nao faca basteira.

  • Skills (vou dizer algo polemico aqui): gerencie tuas skills para serem ao mesmo simples e completas - simples no sentido de ter apenas um objetivo/feature principal (p.ex. autenticacao, esquema de CRUD), mas completas o bastante para cobrir o que voce precisa sobre aquela feature (a skill eh o manual de instrucoes sobre algo, entao ensine o LLM sobre aquele algo, sem ser prolixo nem laconico).

  • Ative/desative suas skills por tarefa (eh uma gambiarra, mas funciona): se vou fazer um plan, deixo certas skills ativadas e outras desativadas. Se vou fazer manutencao em codigo frontend, outras skills. codigo backend/api, outras skills - e faco isso via um script que rodo ANTES de comecar a tarefa. Sim, teu agente/LLM deveria saber fazer isso sozinho, so carregando o que precisa - na pratica, "dou uma forcinha" (quanto menos coisas para distrair o modelo, melhor). Eh um saco ? com certeza - um dia isso vai funcionar melhor, mas eh o que tem para hoje).

  • Use estruturas XML nos prompts: isso ajuda o LLM a se encontrar no meio de tanta confusao e economiza tokens (<blabla>instrucoes</blabla>)

Obrigado por compartilhar !

Saude e Sucesso !

Este post foi favoritado via extensão TABNEWS FAVORITOS

Tem curiosidade sobre IA ? Da uma olhada no meu LIVRO: IA PARA ENGENHEIROS

5

meus literais 2 cents:

    1. O Borys Cherney tem tokens infinitos, então temos que cuidar com as comparações
    1. Realmente a turma se passa com os claude.md e esquece que o negócio come token
1

É um recorte que faltou no post: o Boris não paga a conta de token dele. No meu caso a fatura chega, e foi ela que me empurrou a tirar detalhe do CLAUDE.md e deixar em docs/ referenciado por nome, porque assim só entra na janela quando a tarefa pede.

CLAUDE.md gordo é custo fixo em toda sessão, até nas que não usam nada daquilo.

5

Bom dia, meu bom, realmente é interessante como funciona isso, eu tenho um projeto imenso que dá quase umas 663 linhas somente para o Claude não se perder, e realmente sempre quando abro um novo card para realizar melhorias, ele já entende sobre o projeto e começo as melhorias, raramente preciso corrigir algo que ele fez a correção, somente certifico que está de acordo.
Não sei se é forma que faço que ele fica sucinto e não se perde no que está fazendo. E não viaja muito, mas algumas vezes acontece depende muito de como usei ele durante o dia. Mas ele segue bem fiel ao que está na memória dele.
Parabéns pelo post e realmente depende muito de como você constrói as regras nele.

3

Meus 2 cents extendidos,

Se um dia voce puder compartilhar estas 600 linhas - gostaria muito de ver como voce mantem o modelo na linha.

Ser sucinto eh uma excelente direcao.

Agora o "...depende muito de como usei ele durante o dia..." que me deixa frustrado: as vezes o processo funciona que eh uma beleza, as vezes pega um caminho bem esquisito - e mesmo olhando os LOGs de prompt enviados, contexto gerado, etc, nao consegui chegar a uma conclusao "faca sempre assim que vai dar certo".

Saude e Sucesso !

Este post foi favoritado via extensão TABNEWS FAVORITOS

Tem curiosidade sobre IA ? Da uma olhada no meu LIVRO: IA PARA ENGENHEIROS

1

Bom saber que 663 linhas rodam liso, porque isso reforça a regra que sobrou no post: o tamanho certo é o tamanho do contexto que precisa existir, e projeto imenso pede arquivo imenso.

Aqui o meu quebrou bem antes, na casa das 247, então fiquei curioso pra saber como você organiza as seções. Obrigado por trazer o número real, comentário com dado vale ouro.

4
4

Meus 2 cents extendidos,

Obrigado pelo comentario !

O disable-model-invocation nao eh o objetivo, pois eu quero que o modelo carregue automaticamente, mas apenas um determinado tipo de skills para aquela situacao.

A ativacao/desativacao de CLAUDE.md, AGENTS.md e skills que uso eh via script que faz o rename de arquivo e/ou diretorio, para que naquela tarefa um harness especifico esteja habilitado.

O ponto aqui eh: o harness tende a se tornar extremamente complexo conforme vai cobrindo diversos tipos/casos de uso, entao o objetivo eh simplificar o que o modelo/agente ve antes da tarefa comecar.

Eh possivel fazer isso com subagentes criando estruturas especificas para cada perfil de subagente, mas nem sempre eh o ideal.

Se estou no ponto de criar os CRUDs de um app, entao o harness ativo sabe tudo sobre isso (mas nao sobre outros itens). Se vou trabalhar na criacao dos endpoints tenho um harness bem especifico com regras para protecao, etc.

O conjunto de conhecimentos e habilidades para fazer um sistema sao bem diversas - em uma empresa fisica teriamos diversos departamentos com funcionarios especializados: o que faco eh ter um workspace para cada momento. Na pratica estou descrevendo o que eh usado com agentes/subagentes - mas nem sempre este pipeline/workflow (os subagentes) eh desejado.

Saude e Sucesso !

Este post foi favoritado via extensão TABNEWS FAVORITOS

Tem curiosidade sobre IA ? Da uma olhada no meu LIVRO: IA PARA ENGENHEIROS

1

Teu esquema de renomear o harness por tarefa é a versão honesta do que muita gente finge que o agente faz sozinho. Eu cheguei num meio-termo parecido: rodo uns 60 skills hoje, e o que segurou a bagunça foi caprichar na description do frontmatter, porque é ela que o modelo lê na hora de decidir o que carrega.

Sobre o Lost in the Middle, foi exatamente a linha 138 do experimento 2 que me convenceu. Regra crítica no meio do arquivo é regra que não existe.

O ponto do XML eu assino embaixo, uso tag até em prompt de cron job e o ganho de obediência é visível.

Se um dia você publicar esse script de rename, eu leio na hora. Valeu pela troca, teu comentário completou o post.

1

Eu acredito que ele tenha tokens infinitos. Então pra ele não faz diferença ler todo repositório em cada sessão. Pra mim em projetos grandes funcionou o sistema de atalhos. Deixar uma espécie de sitemap de cada função. E faz sentido porque um repositório que lançaram agora, graphify(acho que assim que escreve) faz algo parecido e promete economizar mais de 90% dos tokens. Portanto o que você puder deixar para facilitar para a IA não ficar pesquisando coisas inuteis acredito ser melhor do ponto de vista econômico.

1

Nunca prestei atenção ao tamanho deste arquivo, sempre coloco instruções que fazem sentido ao contexto imediato do projeto, pois isso varia com o momento do projeto, eu quebro em sprints e tarefas, basicamente em cada uma vai ter uma atualização de contexto, meu foco maior são as specs, que também se atualizam, mas é neles que ficam as regras de negócio, testes e tudo mais. Dessa forma eu tenho várias specs específicas e um AGENTS.MD com contexto geral do que está sendo feito e objetivo do projeto.