karpathy reclamou do claude no x. forrest chang transformou a reclamação em quatro regras e um repositório no github. o repositório atingiu 120.000 estrelas em semanas. a maioria dos desenvolvedores que leem isso ainda usa apenas essas quatro regras. o problema é que elas foram escritas em janeiro. agora é meados de 2026, e o ecossistema do claude code mudou.
este artigo fornece o CLAUDE.md completo com 12 regras, por que cada regra existe, qual falha ela corrige e o que o template original erra silenciosamente. cole-o no final.
O Que É o CLAUDE.md e Por Que a Maioria das Pessoas Erra
CLAUDE.md é um arquivo que você coloca na raiz do seu repositório. o claude code o lê antes de cada sessão. não é um prompt. não é uma lista de preferências. é um sistema operacional para como o claude se comporta no seu código.
a maioria dos desenvolvedores faz uma de três coisas erradas. eles colocam todas as preferências que já tiveram no arquivo até que ele inche além de 4.000 tokens, momento em que a conformidade cai para 30% porque regras importantes ficam enterradas. eles pulam completamente e dão um novo prompt a cada sessão, o que desperdiça cinco vezes mais tokens e produz zero consistência. eles colam um template uma vez, esquecem dele e o veem quebrar silenciosamente ao longo de semanas à medida que o código muda.
a documentação oficial da anthropic é explícita: CLAUDE.md é consultivo. o claude o segue cerca de 80% das vezes com menos de 200 linhas. acima de 200 linhas, a conformidade cai drasticamente. o teto para arquivos CLAUDE.md úteis é curto, preciso e imposto por regras diretas, não sugestões.
As 4 Regras Originais: Comece Aqui Se Você Não Tem Nada
andrej karpathy, ex-diretor de IA na tesla e cofundador da openai, postou um tópico em janeiro de 2026 após semanas de trabalho intensivo com o claude code. não um framework. uma reclamação. três modos de falha que ele continuava encontrando: o claude assume silenciosamente em vez de perguntar, o claude superdimensiona em vez de resolver o mínimo, e o claude toca em código que nunca foi solicitado a tocar.
forrest chang leu o tópico e o escreveu como regras. um arquivo, 65 linhas, no github no dia seguinte. aqui estão as quatro:
Regra 1 - Pense Antes de Codificar
declare suas suposições antes de escrever código. explicite tradeoffs. pergunte antes de adivinhar. questione quando uma abordagem mais simples existir. nunca construa sobre uma suposição não verificada.
Regra 2 - Simplicidade Primeiro
escreva o código mínimo que resolve o problema. sem funcionalidades especulativas. sem abstrações para código usado uma vez. se um engenheiro sênior consideraria complicado demais, simplifique.
Regra 3 - Mudanças Cirúrgicas
toque apenas no que a tarefa exige. não melhore código, comentários ou formatação adjacentes. não refatore o que não está quebrado. corresponda exatamente ao estilo existente.
Regra 4 - Execução Orientada a Objetivos
defina como é o sucesso antes de começar. repita até que o sucesso seja verificado. não liste etapas para o claude seguir. diga ao claude como é o "pronto" e deixe-o encontrar o caminho.
essas quatro regras fecham cerca de 40% dos modos de falha em sessões não supervisionadas do claude code. os 60% restantes vivem em lacunas que o template original não aborda, porque esses problemas não existiam totalmente quando karpathy postou seu tópico.
Por Que o Template Original Precisa Ser Estendido
as quatro regras de karpathy foram criadas para corrigir uma sessão de escrita de código com um único agente. o ecossistema do claude code em 2026 executa configurações multiagente, hooks, bibliotecas de habilidades e fluxos de trabalho de várias etapas que abrangem sessões. o template original não tem nada a dizer sobre nada disso.
quatro lacunas específicas aparecem nas regras originais. primeiro, brigas de agentes: dois agentes editando os mesmos arquivos sem regras de propriedade, pisando silenciosamente nas alterações um do outro. segundo, cascatas de hooks: hooks que disparam em cada chamada de ferramenta, transformando uma solicitação de 200 tokens em 8.000 tokens sem orçamento para pará-la. terceiro, conflitos de carregamento de habilidades: várias habilidades com descrições semelhantes confundem o despachante e carregam a errada. quarto, quebras de sessão em várias etapas: uma refatoração de 6 etapas falha na etapa 4, mas as etapas 5 e 6 são executadas de qualquer maneira e constroem sobre um estado quebrado.
as quatro regras originais não estão erradas. elas estão incompletas. as 8 regras adicionais abaixo fecham essas lacunas específicas.
As 8 Novas Regras: O Que Cada Uma Fecha
----------------------------------—
Regra 5 - Não Use o Modelo para Trabalho Não Linguístico
decisões determinísticas pertencem ao código determinístico. lógica de repetição, limites de roteamento, regras de escalonamento, ramificação baseada em status: nenhum deles deve ser chamadas de LLM. o modelo decide de forma diferente a cada semana com base no que está na janela de contexto. o que parece ser um comportamento consistente é, na verdade, uma variação que ainda não veio à tona.
o incidente específico: uma chamada de LLM para "decidir se deve repetir em caso de 503" funcionou por duas semanas, depois começou a produzir comportamento aleatório porque o modelo começou a ler o corpo da solicitação como contexto para a decisão de repetição. a política se tornou aleatória porque a entrada efetiva era aleatória.
adicione isso ao seu CLAUDE.md:
roteamento, lógica de repetição, ramificação baseada em status e decisões de limite pertencem ao código, não a chamadas de modelo. se a saída de uma decisão é binária ou segue uma regra fixa, escreva a regra em código.
Regra 6 - Orçamentos Rígidos de Tokens, Sem Exceções
todo loop de agente tem uma chance de espiralar. o claude não vai parar uma sessão de depuração de 90 minutos por conta própria. ele continuará iterando porque a iteração é o que lhe foi dito para fazer. orçamentos de tokens são o único mecanismo que impõe uma parada forçada.
o incidente específico: uma sessão de depuração em loop na mesma mensagem de erro de 8KB por 90 minutos. no final, o claude estava sugerindo correções que já havia tentado e abandonado duas horas antes. o contexto estava tão cheio que ele havia perdido o controle de seu próprio raciocínio.
adicione isso:
toda sessão de agente tem um orçamento rígido de tokens. se o orçamento for atingido sem uma solução verificada, pare, resuma as descobertas em um arquivo e saia. não continue além do orçamento.
Regra 7 - Um Agente, Um Diretório
quando dois agentes tocam o mesmo diretório simultaneamente, você obtém corrupção silenciosa de estado. um agente escreve um arquivo enquanto outro o lê. o resultado são dados que nenhum dos agentes esperava e nenhum percebe.
use git worktrees. execute git worktree add ../agent-2-branch feature-branch antes de gerar um segundo agente. cada agente obtém seu próprio diretório de trabalho isolado apontado para seu próprio branch. os agentes nunca compartilham um sistema de arquivos.
adicione isso:
agentes executados em paralelo trabalham em git worktrees separados. dois agentes não tocam o mesmo diretório ao mesmo tempo. cada agente possui seu branch.
Regra 8 - Escreva Arquivos de Ponto de Verificação em Trabalhos de Várias Etapas
qualquer tarefa com mais de três etapas precisa de um arquivo de ponto de verificação. o claude escreve o arquivo após cada etapa com o que foi concluído, o que foi encontrado e o que vem a seguir. se a sessão morrer ou quebrar na etapa 4, a próxima sessão lê o ponto de verificação e continua da etapa 4. sem o ponto de verificação, cada reinicialização volta para a etapa 1.
crie um arquivo chamado PROGRESS.md no seu diretório de trabalho antes de iniciar qualquer tarefa de várias etapas. diga ao claude no seu CLAUDE.md:
para tarefas com mais de três etapas, escreva um arquivo PROGRESS.md após cada etapa. inclua: o que foi feito, o que foi encontrado, o que vem a seguir e o que está bloqueado. se uma sessão terminar antes da conclusão, a próxima sessão lê PROGRESS.md primeiro e continua de onde parou.
Regra 9 - Falhe Alto ou Não Falhe
o claude tem um forte viés para parecer bem-sucedido. ele passará em um teste que na verdade não testa o que você se importava. ele completará uma migração enquanto pula silenciosamente arquivos que deram erro. ele relatará "pronto" em uma tarefa que está 80% concluída.
a regra: se o critério de sucesso não puder ser verificado, a tarefa não está concluída. se uma etapa falhar, pare e relate a falha com detalhes antes de continuar. não encubra erros.
adicione isso:
nunca continue após uma etapa que falhou. se um teste passar, mas não cobrir o comportamento real, diga isso. se uma migração pular arquivos, liste os arquivos pulados e pare. sucesso significa verificável, não relatado.
Regra 10 - Descrições de Habilidades Devem Ser Únicas
as habilidades são carregadas por correspondência de descrição. se duas habilidades têm descrições sobrepostas, o despachante escolhe uma arbitrariamente. a habilidade errada é carregada, a tarefa é executada com instruções ruins, e você nunca vê um erro porque nenhum erro é lançado.
nomeie o trabalho de cada habilidade com uma linguagem que não possa corresponder a nenhuma outra habilidade. "auxiliar de consulta de banco de dados" e "auxiliar de migração de banco de dados" entrarão em conflito. "executar consultas SQL somente leitura no banco de dados de produção" e "executar e verificar scripts de migração de esquema com rollback" não entrarão.
adicione isso:
cada descrição de habilidade deve identificar exclusivamente seu trabalho. duas habilidades não devem ter descrições que possam se aplicar à mesma tarefa. se duas habilidades soarem semelhantes, uma delas precisa ser renomeada antes de ser implantada.
Regra 11 - Separe o Pesquisador do Escritor
a poluição de contexto é real. quando o claude faz pesquisa e escrita na mesma sessão, o ruído da pesquisa degrada a escrita. ele puxa tangentes, atenua conclusões que não precisa atenuar e perde a linha de argumentação limpa que teria começando do zero.
gere um subagente de pesquisa para qualquer tarefa que exija ler mais de cinco arquivos ou consultar mais de duas fontes. obtenha um relatório estruturado de volta. inicie uma sessão limpa para a escrita ou implementação com apenas o relatório no contexto.
adicione isso:
pesquisa e implementação são sessões separadas. um subagente pesquisador lê arquivos, executa consultas e retorna um resumo estruturado. a sessão de implementação começa do zero com esse resumo como sua única entrada. nunca mescle pesquisa e escrita em uma sessão.
Regra 12 - Hooks Também Precisam de Orçamentos
hooks disparam em cada chamada de ferramenta. um hook que executa um linter, um formatador, um gravador de log e uma verificação de segurança em cada gravação de arquivo está executando quatro processos por chamada de ferramenta. em uma sessão com 200 chamadas de ferramenta, isso são 800 processos sendo executados em segundo plano, a maioria deles redundantes, todos consumindo tokens.
cada hook que você adiciona precisa de uma condição de escopo: executar apenas em gravações de arquivos em diretórios específicos, executar apenas quando uma extensão de arquivo específica for tocada, executar apenas após o término da sessão em vez de após cada chamada de ferramenta. hooks sem condições de escopo degradarão o desempenho da sessão de forma invisível.
adicione isso:
todo hook tem uma condição de escopo explícita. nenhum hook é executado incondicionalmente em cada chamada de ferramenta. agrupe logs para o final da sessão. execute linters apenas em arquivos alterados. execute verificações de segurança apenas em arquivos fora do diretório de teste.
O CLAUDE.md Completo com 12 Regras - Cole Isso
copie este arquivo para a raiz do seu repositório. preencha as seções marcadas com colchetes. o arquivo inteiro fica com menos de 100 linhas, o que mantém a conformidade acima de 80%.
CLAUDE.md
Projeto
[uma frase: o que este código faz e qual stack de tecnologia ele usa]
Regras Comportamentais
Pense Antes de Codificar
declare suas suposições antes de escrever código. explicite tradeoffs. pergunte antes de adivinhar qualquer coisa que afete arquitetura ou dados. questione quando uma abordagem mais simples existir.
Simplicidade Primeiro
escreva o código mínimo que resolve o problema. sem funcionalidades especulativas. sem abstrações para código de uso único. se um engenheiro sênior consideraria complicado demais, simplifique.
Mudanças Cirúrgicas
toque apenas no que a tarefa exige. não melhore código, formatação, comentários ou nomenclatura adjacentes que não faziam parte do pedido. corresponda exatamente ao estilo de código existente.
Execução Orientada a Objetivos
defina como é o sucesso antes de começar. repita até que essa definição seja atendida e verificada. não peça instruções passo a passo. descubra o caminho.
Sem Chamadas de Modelo para Decisões Determinísticas
roteamento, lógica de repetição, ramificação baseada em status e decisões de limite pertencem ao código, não a chamadas de LLM. se uma regra pode ser escrita, escreva-a.
Orçamentos Rígidos de Tokens
toda sessão tem um limite rígido de tokens: [defina seu número, ex.: 50.000 tokens]. se o limite for atingido sem uma solução verificada, escreva as descobertas em um arquivo e pare. não continue além do orçamento.
Um Agente, Um Diretório
agentes executados em paralelo trabalham em git worktrees separados. dois agentes não compartilham um diretório. se você precisar de um segundo agente, execute: git worktree add ../agent-2 [nome-do-branch]
Ponto de Verificação em Trabalhos de Várias Etapas
para qualquer tarefa com mais de três etapas, crie PROGRESS.md no diretório de trabalho. escreva nele após cada etapa: o que foi feito, o que foi encontrado, o que vem a seguir, o que está bloqueado. se a sessão terminar antes da conclusão, a próxima sessão lê PROGRESS.md primeiro.
Falhe Alto
se uma etapa falhar, pare e relate a falha com detalhes antes de continuar. se um teste passar, mas não cobrir o comportamento real, diga isso. sucesso significa verificável, não relatado.
Descrições Únicas de Habilidades
cada habilidade cobre exatamente um trabalho. sua descrição não pode se aplicar a nenhuma outra habilidade no projeto. se duas habilidades se sobrepuserem na descrição, renomeie antes de implantar.
Pesquisa e Implementação São Sessões Separadas
use um subagente para qualquer tarefa que exija ler mais de cinco arquivos ou consultar mais de duas fontes. obtenha um relatório estruturado. inicie uma sessão limpa para implementação com apenas esse relatório como entrada.
Apenas Hooks com Escopo
todo hook tem uma condição explícita: extensão de arquivo, caminho de diretório ou evento de sessão. nenhum hook é executado incondicionalmente em cada chamada de ferramenta. agrupe logs para o final da sessão quando possível.
O Que Não Tocar
[liste diretórios ou arquivos que o claude nunca deve modificar: ex.: /secrets, /migrations/archive, /prod-config]
Critério de Sucesso Padrão
quando em dúvida sobre se uma tarefa está concluída: o teste passa, o build é bem-sucedido e a saída é verificável por algo diferente do próprio julgamento do claude? se não para qualquer um deles, não está concluída.
Quatro Lugares Onde o Template Original Quebra Silenciosamente
mesmo com apenas as quatro regras originais, existem quatro condições específicas onde o template produz o comportamento errado e não te avisa.
primeiro: sessões longas com contexto acumulado. a regra de execução orientada a objetivos de karpathy diz ao claude para repetir até verificar. em uma sessão longa, "verificado" fica turvo à medida que o contexto se enche. o claude começa a verificar contra um modelo degradado do que deveria fazer. a correção é a regra 6 (orçamento de token) forçando uma parada forçada.
segundo: configurações multiagente. a regra de mudanças cirúrgicas diz a cada agente para tocar apenas no que deve. mas com dois agentes e nenhuma regra de propriedade de diretório, "o que deve" se sobrepõe. a regra 7 (um agente, um diretório) é a peça que faltava.
terceiro: habilidades paralelas com trabalhos semelhantes. o template original não tem nada sobre habilidades. a regra 10 (descrições únicas de habilidades) fecha a lacuna de ambiguidade do despachante.
quarto: sessões que terminam no meio da tarefa. a execução orientada a objetivos assume que a sessão é executada até a conclusão. ela não tem instrução para o que fazer se a sessão morrer na etapa 4 de 8. a regra 8 (arquivos de ponto de verificação) dá à próxima sessão um ponto de partida.
nenhuma dessas são bugs nas regras originais. são lacunas que as regras originais não foram escritas para cobrir.
O Número Que Explica as Estrelas do GitHub
120.000 desenvolvedores marcaram com estrela um arquivo de texto de 65 linhas. sem código. sem biblioteca. sem framework. um arquivo com quatro regras.
o número que explica isso: 41% de taxa de erro em sessões não supervisionadas do claude code sem CLAUDE.md. 11% com as quatro regras originais. 3% com as doze completas.
uma redução de 38 pontos percentuais nos erros não é uma melhoria marginal. para qualquer equipe executando claude code em trabalho real de produção, é a diferença entre um agente em que você pode confiar para executar durante a noite e um que você precisa monitorar.
o arquivo no final deste artigo leva cinco minutos para colar e preencher. a primeira sessão depois que você fizer isso será diferente. não porque o modelo mudou. porque o modelo finalmente sabe como seu mundo funciona.
Marque isto e cole as 12 regras no seu CLAUDE.md hoje à noite.
Compartilhe se achou útil.
