Karpathy reclamou do Claude no X. Forrest Chang transformou a reclamação em quatro regras e um repositório no GitHub. O repositório alcançou 120.000 estrelas em semanas. A maioria dos desenvolvedores lendo 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 elimina e o que o template original erra silenciosamente. Cole-o no final.
O que é CLAUDE.md e por que a maioria das pessoas entende errado
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 na sua base de 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 infle para mais de 4.000 tokens, momento em que a conformidade cai para 30% porque regras importantes são enterradas. Eles pulam o arquivo completamente e redefinem o prompt a cada sessão, o que desperdiça cinco vezes os tokens e produz zero consistência. Eles colam um template uma vez, esquecem dele e observam ele quebrar silenciosamente ao longo de semanas à medida que sua base de 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 meio de 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, publicou 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 silenciosamente assume 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.
Forrest Chang leu o tópico e 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. Superficie trade-offs. Pergunte antes de adivinhar. Critique quando uma abordagem mais simples existir. Nunca construa com base em 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 chamaria de 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 por Objetivos
Defina como é o sucesso antes de começar. Itere até que o sucesso seja verificado. Não liste etapas para o Claude seguir. Diga ao Claude como é "pronto" e deixe-o encontrar o caminho.
Essas quatro regras eliminam 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 publicou seu tópico.
Por que o Template Original Precisa Ser Estendido
As quatro regras de Karpathy foram construídas para consertar uma sessão de codificação com agente único. 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, conflitos entre agentes: dois agentes editando os mesmos arquivos sem regras de propriedade, pisando nas alterações um do outro silenciosamente. Segundo, cascatas de hooks: hooks que disparam em toda 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: múltiplas habilidades com descrições semelhantes confundem o dispatcher 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 desses deve ser chamada 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 erro 503" funcionou por duas semanas, então 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 se tornou 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 for binária ou seguir uma regra fixa, escreva a regra em código.
Regra 6 - Orçamentos de Token Rígidos, 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 iteração é o que lhe foi dito para fazer. Orçamentos de token 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 de token rígido. 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 no mesmo diretório simultaneamente, você obtém corrupção de estado silenciosa. Um agente escreve um arquivo enquanto outro o está lendo. 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 executando em paralelo trabalham em git worktrees separados. Dois agentes nunca tocam no mesmo diretório ao mesmo tempo. Cada agente possui seu branch.
Regra 8 - Escreva Arquivos de Checkpoint em Trabalhos de Múltiplas Etapas
Qualquer tarefa com mais de três etapas precisa de um arquivo de checkpoint. 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 checkpoint e continua da etapa 4. Sem o checkpoint, 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 múltiplas 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 silenciosamente pula arquivos que falharam. Ele reportará "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 reporte a falha com detalhes antes de continuar. Não enxovalhe erros.
Adicione isso:
Nunca continue além de 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 reportado.
Regra 10 - Descrições de Habilidades Devem Ser Únicas
Habilidades são carregadas por correspondência de descrição. Se duas habilidades têm descrições sobrepostas, o dispatcher escolhe uma arbitrariamente. A habilidade errada carrega, 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 traz tangentes, modera conclusões que não precisam ser moderadas e perde a linha de argumentação limpa que teria começando do zero.
Gere um subagente de pesquisa para qualquer tarefa que exija a leitura de mais de cinco arquivos ou a consulta de 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 toda chamada de ferramenta. Um hook que executa um linter, um formatador, um gravador de log e uma verificação de segurança em toda escrita de arquivo está executando quatro processos por chamada de ferramenta. Em uma sessão com 200 chamadas de ferramenta, isso é 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 escritas de arquivo 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:
Cada hook tem uma condição de escopo explícita. Nenhum hook é executado incondicionalmente em toda 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 permanece com menos de 100 linhas, o que mantém a conformidade acima de 80%.
CLAUDE.md
Projeto
[uma frase: o que esta base de código faz e qual pilha de tecnologia usa]
Regras Comportamentais
Pense Antes de Codificar
Declare suas suposições antes de escrever código. Superficie trade-offs. Pergunte antes de adivinhar em qualquer coisa que afete arquitetura ou dados. Critique 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 chamaria de 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 fizeram parte da solicitação. Corresponda exatamente ao estilo de código existente.
Execução Orientada por Objetivos
Defina como é o sucesso antes de começar. Itere 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 de Token Rígidos
Toda sessão tem um limite de token rígido: [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 executando em paralelo trabalham em git worktrees separados. Dois agentes nunca compartilham um diretório. Se você precisar de um segundo agente, execute: git worktree add ../agent-2 [nome-do-branch]
Checkpoint em Trabalho de Múltiplas 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 reporte 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 reportado.
Descrições de Habilidades Únicas
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 a leitura de mais de cinco arquivos ou a consulta de 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
Cada 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 toda 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 estiver em dúvida se uma tarefa está concluída: o teste passa, a compilação é bem-sucedida 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ído.
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 por objetivos de Karpathy diz ao Claude para iterar até verificar. Em uma sessão longa, "verificado" fica obscuro à 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 de habilidades únicas) fecha a lacuna de ambiguidade do dispatcher.
Quarto: sessões que terminam no meio da tarefa. A execução orientada por objetivos assume que a sessão é executada até a conclusão. Ela não tem instrução sobre o que fazer se a sessão morrer na etapa 4 de 8. A regra 8 (arquivos de checkpoint) dá à próxima sessão um ponto de partida.
Nenhum destes são bugs nas regras originais. Eles 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 em 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 babysitar.
O arquivo no final deste artigo leva cinco minutos para colar e preencher. A primeira sessão depois que você fizer isso parecerá 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.
Reposte se achou útil.
